Предупреждение! Этот перевод сильно устарел, пользуйтесь, пожалуйста, оригиналом.

Использование git для работы с исходным кодом сайта

Введение

Git представляет собой систему управления версиями, которая помогает нескольким людям работать над одним и тем же материалом одновременно. Каждый пользователь имеет локальную копию основного репозитория. Локальные копии могут быть на одной и той же машине или в любом другом месте во всём мире. Пользователи могут менять локальную копию по своему желанию, а когда изменённый материал готов, вносить (commit) изменения и отправлять (push) их в основной репозиторий.

Git не позволит отправить ваши изменения в случае, если удалённый репозиторий содержит более новые коммиты (изменения), чем ваша локальная копия той же ветки. В таком случае, когда имеет место конфликт, сначала загрузите и обновите вашу локальную копию и при необходимости выполните rebase ваших изменений так, чтобы они были размещены после последнего коммита.

Доступ к git-репозиторию с правами на запись

Весь исходный код веб-сайта Debian управляется Git. Исходный код расположен по адресу https://salsa.debian.org/webmaster-team/webwml. По умолчанию гостевые пользователи не могут отправлять в этот репозиторий свои изменения. Вам требуется некоторого вида разрешение для того, чтобы получить права на запись в этот репозиторий.

Неограниченный доступ с правами на запись

Если вам нужен неограниченный доступ к репозиторию с правами на запись (например, вы собираетесь часто вносить правки), то попросите об этом через веб-интерфейс https://salsa.debian.org/webmaster-team/webwml после выполнения входа в платформу Debian Salsa.

Если вы являетесь новичком в работе над веб-сайтом Debian и пока не имеете опыта, то до запроса доступа также отправьте сообщение по адресу [email protected], в котором укажите информацию о себе. В своём сообщении напишите что-нибудь полезное, например, то, над каким языком или над какой частью веб-сайта вы собираетесь работать, а также кто может за вас поручиться.

Запись в репозиторий через запросы слияний

Если вы не собираетесь получать неограниченный доступ с правами на запись в этот репозиторий или вы не можете этого сделать, то вы всегда можете отправить запрос на слияние ваших изменений, что позволит остальным разработчикам проверить и принять вашу работу. Отправляйте запросы на слияние с помощью стандартной процедуры, предоставляемой платформой Salsa GitLab через веб-интерфейс (подробности см. в Алгоритм копирования проекта и Если вы работаете с форком).

Запросы слияний не отслеживаются всеми разработчиками веб-сайта, поэтому они не всегда обрабатываются во время. Если вы не уверены в том, будут ли приняты ваши изменения, то отправьте сообщение электронной почты в список рассылки debian-www и попросите проверить ваши правки.

Работа с репозиторием

Получение локальной копии репозитория

Во-первых, для работы с репозиторием вам необходимо установить git. Во-вторых, вам нужно настроить информацию о пользователе и электронной почте (чтобы узнать о том, как это сделать, обратитесь к общей документации git). В-третьих, вы можете клонировать репозиторий (другими словами, сделать его локальную копию) двумя способами.

При работе над webwml рекомендуется сначала зарегистрировать учётную запись на salsa.debian.org и включить SSH-доступ git, загрузив открытый SSH-ключ в вашу учётную запись salsa. См. справочные страницы по salsa, где вы найдёте дополнительную информацию о том, как это сделать. Далее, вы можете клонировать репозиторий webwml с помощью следующей команды:

   git clone [email protected]:webmaster-team/webwml.git

Если у вас нет учётной записи salsa, то вы можете клонировать репозиторий по протоколу HTTPS:

  git clone https://salsa.debian.org/webmaster-team/webwml.git

Это приведёт к созданию точной локальной копии репозитория, но вы не сможете напрямую вносить свои изменения в основной репозиторий.

Для клонирования всего репозитория webwml требуется загрузить около 500 МБ данных, поэтому это может быть затруднительно для тех, кто имеет медленное или нестабильное соединение. Для начала можно попробовать сделать поверхностное клонирование с минимальной глубиной:

  git clone [email protected]:webmaster-team/webwml.git --depth 1

После получения рабочего (поверхностного) репозитория, вы можете загрузить остальные части и преобразовать их в полный локальный репозиторий: 

  git fetch --deepen=1000 # загрузить ещё 1000 коммитов
  git fetch --unshallow   # загрузить все отсутствующие коммиты и преобразовать репозиторий

Частичная выгрузка

Вы можете создать выгрузку только для некоторого подмножества страниц следующим образом:

   $ git clone --no-checkout [email protected]:webmaster-team/webwml.git
   $ cd webwml
   $ git config core.sparseCheckout true
   В webwml создайте файл .git/info/sparse-checkout с приблизительно следующим содержимым
   (Если вам нужны только базовые файлы, английский, каталонский и испанский языки):
      /*
      !/[a-z]*/
      /english/
      /catalan/
      /spanish/
   Далее:
   $ git checkout --

Отправка локальных изменений

Поддержка локальной копии в актуальном состоянии

Каждые несколько дней (и до того как что-нибудь отредактировать!) вам следует выполнять

   git pull

для загрузки изменённых файлов из репозитория.

Настоятельно рекомендуется поддерживать ваш локальный рабочий git-каталог в чистом состоянии до выполнения "git pull" и последующего редактирования. Если у вас имеются невнесённые в коммит изменения или локальные коммиты, которые не были отправлены в текущую ветку удалённого репозитория, то выполнение "git pull" приведёт к автоматическому созданию коммитов слияния или даже завершится ошибкой из-за конфликта изменений. Рекомендуется сохранять вашу незавершённую работу в другой ветке или использовать такие команды как "git stash".

Внимание: git является распределённой (а не централизованной) системой управления версиями. Это означает, что когда вы вносите изменения (делаете коммит), они лишь сохраняются в вашей локальной копии репозитория. Чтобы поделиться изменениями с другими, вам следует отправить (push) их в центральный репозиторий на salsa.

Пример редактирования файлов на английском языке

Ниже предлагается пример редактирования файлов на английском языке в репозитории исходного кода веб-сайта. После получения локальной копии репозитория с помощью команды "git clone" и до начала редактирования, выполните следующую команду: 

   $ git pull

Теперь вы вносите свои правки в файлы. Затем вносите изменения в ваш локальный репозиторий с помощью следующих команд:

   $ git add путь/к/файлам
   $ git commit -m "Ваше сообщение о коммите"

Если у вас имеется неограниченный доступ с правами на запись в удалённый репозиторий webwml, то вы можете отправить ваши изменения напрямую в репозиторий Salsa:

   $ git push

Если у вас нет прямого доступа с правами на запись в репозиторий webwml, то отправьте ваши изменения в виде запроса слияния. Такая возможность предоставляется платформой Salsa GitLab через веб-интерфейс, либо попросите помощи у других разработчиков.

Таков весьма краткий и упрощённый обзор того, как использовать git для работы с исходным кодом веб-сайта Debian. Дополнительную информацию о git можно найти в документации по git.

Закрытие ошибок Debian через коммиты git

Если вы добавите Closes: #nnnnnn в сообщение о вашем коммите, то ошибка с номером #nnnnnn будет автоматически закрыта в тот момент, когда вы отправите ваши изменения. Точная форма сообщения описана в Политике Debian.

Ссылки HTTP/HTTPS

Многие веб-сайты Debian поддерживают SSL/TLS, поэтому там, где это возможно, используйте ссылки HTTPS. Тем не менее, некоторые веб-сайты Debian/DebConf/SPI/другие не имеют поддержки HTTPS или используют сертификаты SPI (которые не входят в число доверенных во всех браузерах). Для того, чтобы не создавать проблемы для пользователей, не использующих Debian, не используйте для таких сайтов ссылки HTTPS.

Репозиторий git будет отклонять коммиты, содержащие ссылки HTTP на веб-сайты Debian, поддерживающие HTTPS или содержащие ссылки HTTPS для веб-сайтов Debian/DebConf/SPI, о которых известно, что они не поддерживают HTTPS, либо используют сертификаты, заверенные только SPI.

Работа над переводами

Переводы всегда должны быть в актуальном состоянии и должны соответствовать оригинальному файлу на английском языке. Заголовок "translation-check" в переведённых файлах используется для отслеживания того, на какой версии файла на английском языке основывается текущий перевод. Если вы изменяете переведённые файлы, то вам следует обновить и заголовок translation-check так, чтобы он соответствовал хэшу коммита git соответствующего изменения оригинального файла (обычно на английском языке). Узнать хэш можно с помощью команды

$ git log путь/к/файлу/оригинала

Если вы создаёте новый перевод файла, то используйте сценарий copypage.pl, который создаст шаблон для вашего языка, включающий правильный заголовок перевода.

Изменение перевода с помощью smart_change.pl

smart_change.pl представляет собой сценарий, созданный для облегчения одновременного обновления оригинальных файлов и их переводов. Имеются два способа использования этого сценария, которые зависят от того, какие изменения вы вносите.

Чтобы использовать smart_change только для обновления заголовков translation-check в случае, если вы работаете над файлами вручную, поступайте следующим образом:

  1. Внесите изменения в оригинальный файл или файлы, сделайте коммит
  2. Обновите переводы
  3. Запустите smart_change.pl — он подхватит изменения и обновит заголовки в переведённых файлах
  4. Проверьте изменения (напр., с помощью "git diff")
  5. Сделайте коммит с изменениями переводов

Также вы можете использовать smart_change с регулярным выражением для того, чтобы сделать несколько изменений в разных файлах за один раз. Это можно сделать следующим образом:

  1. Запустите smart_change.pl -s s/ПЕРВОЕ/ВТОРОЕ/ оригинал1 оригинал2 ...
  2. Проверьте изменения (напр., с помощью git diff)
  3. Сделайте коммит изменений оригинальных файлов
  4. Запустите smart_change.pl оригинал1 оригинал2 (то есть, без регулярного выражения); это приведёт к обновлению заголовков в переведённых файлах
  5. Наконец сделайте коммит с изменениями переводов

Теперь требуется немного больше работы, чем раньше (нужно два коммита), но это неизбежно из-за того, что так работают хэши коммитов git.

Получение уведомлений

Получение уведомлений о коммитах

Мы настроили проект webwml в Salsa так, что коммиты показываются в IRC-канале #debian-www.

Если вы хотите получать уведомления по электронной почте при добавлении коммитов в репозиторий webwml, то подпишитесь на псевдопакет www.debian.org через tracker.debian.org и включите ключевое слово vcs. Это можно сделать следующим образом (это нужно сделать только один раз):

Получение уведомлений о запросах слияния

Если вы хотите получать сообщения с уведомлениями при создании нового запроса слияния, отправленного через веб-интерфейс репозитория webwml на платформе Salsa GitLab, то вы можете изменить свои настройки уведомлений для репозитория webwml через веб-интерфейс, следуя приведённым ниже шагам: