perlgit

СОДЕРЖАНИЕ

• НАЗВАНИЕ
• ОПИСАНИЕ
• КЛОНИРОВАНИЕ РЕПОЗИТОРИЯ
• РАБОТА С РЕПОЗИТОРИЕМ
  • Определение вашего статуса
  • Процесс создания патчей
  • Примечание о производных файлах
  • Очистка рабочей директории
  • Бисекция
  • Ветви тем и переписывание истории
  • Вставки
• ДОСТУП НА ЗАПИСЬ В РЕПОЗИТОРИЙ GIT
  • Работа с запросами на включение изменений (GitHub pull requests)
  • Принятие патча
  • Внесение изменений в blead
  • О слиянии и перебазировании
  • Внесение изменений в версии поддержки
  • Использование ветки smoke-me для тестирования изменений

НАЗВАНИЕ

perlgit - Подробная информация о git и репозитории Perl

ОПИСАНИЕ

В данном документе подробно описаны методы использования git для разработки Perl. Если вы просто хотите внести быстрый патч, сначала ознакомьтесь с документом perlhack. Этот документ предназначен для регулярных участников разработки Perl, включая тех, у кого есть доступ на запись в репозиторий git.

КЛОНИРОВАНИЕ РЕПОЗИТОРИЯ

Весь исходный код Perl хранится централизованно в репозитории Git на github.com.

Вы можете создать только для чтения клон репозитория, выполнив:

% git clone git@github.com:Perl/perl5.git perl

Если вы не можете использовать этот метод из-за правил брандмауэра, вы также можете клонировать через http:

% git clone https://github.com/Perl/perl5.git perl

РАБОТА С РЕПОЗИТОРИЕМ

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

% git branch
* blead

Использование опции -a в branch также покажет отслеживаемые удаленные ветви в репозитории:

% git branch -a
* blead
  origin/HEAD
  origin/blead
...

Ветви, начинающиеся с "origin", соответствуют "git remote", с которого вы клонировали (он называется "origin"). Каждая ветвь на удаленном сервере точно отслеживается этими ветвями. НИКОГДА не работайте с этими отслеживаемыми удалёнными ветвями. Вы всегда работаете только в локальных ветвях. Локальные ветви могут быть настроены на автоматическое слияние (при выполнении pull) из выделенной удалённой ветви. Такое настройка применяется к основной ветви blead , которая будет настроена на слияние с удаленной ветвью origin/blead.

Вы можете просмотреть последние коммиты:

% git log

И выполнить pull новых изменений из репозитория и обновить ваш локальный репозиторий (сначала убедитесь, что он чистый):

% git pull

Предполагая, что мы находимся на ветви blead сразу после выполнения pull, эта команда примерно эквивалентна:

% git fetch
% git merge origin/blead

Фактически, если вы хотите обновить ваш локальный репозиторий, не трогая рабочую директорию, вы можете сделать:

% git fetch

А если вы хотите обновить отслеживаемые удалённые ветви для всех определённых удалённых репозиториев одновременно, вы можете сделать:

% git remote update

Ни одна из этих последних двух команд не обновит вашу рабочую директорию, однако обе обновит отслеживаемые удалённые ветви в вашем репозитории.

Чтобы создать локальную ветвь из удалённой ветви:

% git checkout -b maint-5.10 origin/maint-5.10

Чтобы вернуться обратно к blead:

% git checkout blead

Определение вашего статуса

Наиболее часто используемая команда git, вероятно, будет

% git status

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

% git status
On branch blead
Your branch is ahead of 'origin/blead' by 1 commit.

Changes to be committed:
  (use "git reset HEAD <file>..." to unstage)

      modified:   pod/perlgit.pod

Changes not staged for commit:
  (use "git add <file>..." to update what will be committed)
  (use "git checkout -- <file>..." to discard changes in working
                                                             directory)

      modified:   pod/perlgit.pod

Untracked files:
  (use "git add <file>..." to include in what will be committed)

      deliberate.untracked

Это показывает, что для коммита были подготовлены изменения в этом документе, а также, что в рабочей директории есть другие изменения, которые ещё не подготовлены. Также отображается неотслеживаемый файл в рабочей директории, и, как видно, показывает, как всё это изменить. Также показывает, что в рабочей ветви blead есть один коммит, который ещё не был опубликован в удалённый репозиторий origin. ПРИМЕЧАНИЕ: Этот вывод также отображается в качестве шаблона, если вы не укажете сообщение для git commit.

Процесс создания патчей

Сначала, пожалуйста, прочитайте perlhack для получения подробной информации о разработке в Perl. Этот документ содержит много деталей о том, как создать хороший патч.

Если у вас уже есть репозиторий Perl, вы должны убедиться, что вы находитесь на ветке blead, и ваш репозиторий обновлён:

% git checkout blead
% git pull

Предпочтительнее создавать патч на основе последней версии blead, так как именно здесь происходит разработка всех изменений, кроме критических исправлений ошибок. Критические исправления ошибок должны создаваться на соответствующих ветках maint или должны быть представлены с заметкой, указывающей на все ветки, где исправление должно быть применено.

Теперь, когда всё обновлено, нам нужно создать временную новую ветвь для этих изменений и переключиться на неё:

% git checkout -b orange

что является сокращённой формой

% git branch orange
% git checkout orange

Создание ветви темы упрощает для разработчиков перебазирование или слияние обратно в основную ветку blead для более линейной истории. Если вы не работаете в ветке темы, разработчику нужно вручную выполнить cherry-pick ваших изменений в blead, прежде чем они смогут быть применены.

Это вызовет нарекания на perl5-porters, так что не делайте этого. Будьте крутыми.

Затем внесите свои изменения. Например, если Леон Брокард изменит своё имя на Оранжевый Брокард, мы должны изменить его имя в файле AUTHORS:

% perl -pi -e 's{Leon Brocard}{Orange Brocard}' AUTHORS

Вы можете увидеть, какие файлы были изменены:

% git status
On branch orange
Changes to be committed:
  (use "git reset HEAD <file>..." to unstage)

   modified:   AUTHORS

И вы можете увидеть изменения:

% git diff
diff --git a/AUTHORS b/AUTHORS
index 293dd70..722c93e 100644
--- a/AUTHORS
+++ b/AUTHORS
@@ -541,7 +541,7 @@    Lars Hecking              <lhecking@nmrc.ucc.ie>
 Laszlo Molnar                  <laszlo.molnar@eth.ericsson.se>
 Leif Huhn                      <leif@hale.dkstat.com>
 Len Johnson                    <lenjay@ibm.net>
-Leon Brocard                   <acme@astray.com>
+Orange Brocard                 <acme@astray.com>
 Les Peters                     <lpeters@aol.net>
 Lesley Binks                   <lesley.binks@gmail.com>
 Lincoln D. Stein               <lstein@cshl.org>

Теперь совершите коммит изменений локально:

% git commit -a -m 'Rename Leon Brocard to Orange Brocard'
Created commit 6196c1d: Rename Leon Brocard to Orange Brocard
 1 files changed, 1 insertions(+), 1 deletions(-)

Опция -a используется для включения всех отслеживаемых git файлов, которые вы изменили. Если в данный момент вы хотите сделать коммит только некоторых из файлов, над которыми вы работали, вы можете опустить -a и использовать команду git add FILE ... перед коммитом. git add --interactive позволяет даже просто сделать коммит части файлов, а не всех изменений в них.

Опция -m используется для указания сообщения коммита. Если вы её опустите, git откроет текстовый редактор для создания сообщения интерактивно. Это полезно, когда изменения более сложные, чем пример, и, в зависимости от редактора, для того, чтобы знать, что первая строка сообщения коммита не превышает допустимого максимума в 50 символов. См. "Сообщение коммита" в perlhack для получения дополнительной информации о том, что делает сообщение коммита хорошим.

После завершения написания сообщения коммита и выхода из редактора, git запишет ваши изменения на диск и сообщит вам что-то вроде этого:

Created commit daf8e63: explain git status and stuff about remotes
 1 files changed, 83 insertions(+), 3 deletions(-)

Если вы повторно запустите git status, вы должны увидеть что-то вроде этого:

% git status
On branch orange
Untracked files:
  (use "git add <file>..." to include in what will be committed)

      deliberate.untracked

nothing added to commit but untracked files present (use "git add" to
                                                                 track)

В случае сомнений, перед любыми другими действиями проверьте свой статус и внимательно его прочитайте, многие вопросы отвечаются непосредственно выводом git status.

Вы можете изучить свой последний коммит с помощью:

% git show HEAD

и если вы не довольны ни описанием, ни самим патчем, вы можете исправить это, отредактировав файлы ещё раз, и затем выполнить:

% git commit -a --amend

Теперь создайте fork на GitHub, чтобы опубликовать свою ветвь, и добавьте его как удалённый репозиторий, если вы этого ещё не сделали, как описано в документации GitHub по https://help.github.com/en/articles/working-with-forks:

% git remote add fork git@github.com:MyUser/perl5.git

И опубликуйте ветвь в ваш fork:

% git push -u fork orange

Теперь вы должны отправить запрос на включение изменений (Pull Request, PR) на GitHub с новой ветви в blead. Для получения более подробной информации см. документацию GitHub по https://help.github.com/en/articles/creating-a-pull-request-from-a-fork.

Вы также можете отправить файлы патчей напрямую на perl5-porters@perl.org, если патч ещё не готов к применению, но предназначен для обсуждения.

Чтобы создать файл патча для всех ваших локальных изменений:

% git format-patch -M blead..
0001-Rename-Leon-Brocard-to-Orange-Brocard.patch

Или для большого количества изменений, например, из ветви темы:

% git format-patch --stdout -M blead.. > topic-branch-changes.patch

Если вы хотите удалить свою временную ветвь, вы можете сделать это с помощью:

% git checkout blead
% git branch -d orange
error: The branch 'orange' is not an ancestor of your current HEAD.
If you are sure you want to delete it, run 'git branch -D orange'.
% git branch -D orange
Deleted branch orange.

Примечание о производных файлах

Обратите внимание, что многие файлы в дистрибутиве являются производными — избегайте их редактирования, потому что git не увидит изменений, а процесс сборки перезапишет их. Редактируйте оригиналы. Большинство утилит (например, perldoc) относятся к этой категории, т. е. отредактируйте utils/perldoc.PL, а не utils/perldoc. Аналогично, не создавайте патчи для файлов в $src_root/ext из их копий в $install_root/lib. Если вы не уверены в правильном расположении файла, который мог быть скопирован во время сборки исходного дистрибутива, обратитесь к MANIFEST.

Очистка рабочей директории

Команда git clean с различными аргументами может использоваться как замена для make clean.

Чтобы сбросить вашу рабочую директорию в первоначальное состояние, вы можете сделать:

% git clean -dxf

Однако имейте в виду, что это удалит ВСЕ неотслеженные данные. Вы можете использовать

% git clean -Xf

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

Если вы хотите только отменить некоторые несохранённые изменения, вы можете использовать git checkout и указать список файлов для отмены, или git checkout -f для отмены всех.

Если вы хотите отменить один или несколько коммитов, вы можете использовать git reset.

Бисекция

git предоставляет встроенный способ определения коммита, который должен быть виновником введения данной ошибки. git bisect выполняет двоичный поиск в истории, чтобы найти первый коммит, вызвавший сбой. Это быстро, мощно и гибко, но требует некоторых настроек, а для автоматизации процесса требуется вспомогательный скрипт оболочки.

Ядро предоставляет программу-обёртку Porting/bisect.pl, которая пытается максимально упростить процесс, делая бисекцию такой же простой, как запуск Perl-один.линейки. Например, если вы хотите узнать, когда это стало ошибкой:

perl -e 'my $a := 2'

вы просто запустите это:

.../Porting/bisect.pl -e 'my $a := 2;'

Используя Porting/bisect.pl, одной командой (и без других файлов) легко узнать

• Какой коммит привел к поломке этого примера кода?

• Какой коммит привел к запуску этого примера кода?

• Какой коммит добавил первый файл, соответствующий этому регулярному выражению?

• Какой коммит удалил последний файл, соответствующий этому регулярному выражению?

обычно без необходимости знать, какие версии perl использовать в качестве начальной и конечной ревизий, так как Porting/bisect.pl автоматически ищет самую раннюю стабильную версию, для которой тестовый случай проходит. Запустите Porting/bisect.pl --help для получения полной документации, включая способы установки Configure и параметров времени сборки.

Если вам нужна большая гибкость, чем предлагает Porting/bisect.pl, вам нужно будет запустить git bisect самостоятельно. Это наиболее полезно для автоматизации построения и тестирования ревизий perl. Для этого вам понадобится скрипт оболочки для git для тестирования конкретной ревизии. Пример скрипта — Porting/bisect-example.sh, который следует скопировать вне репозитория, так как процесс бисекции сбросит состояние на чистую версию при его запуске. Приведенные ниже инструкции предполагают, что вы скопировали его как ~/run и затем отредактировали его соответствующим образом.

Сначала вы переходите в режим бисекции:

% git bisect start

Например, если ошибка присутствует в HEAD, но отсутствовала в 5.10.0, git узнает об этом, когда вы введете:

% git bisect bad
% git bisect good perl-5.10.0
Bisecting: 853 revisions left to test after this

Это приводит к проверке коммита, являющегося медианой между HEAD и perl-5.10.0. Затем вы можете запустить процесс бисекции с помощью:

% git bisect run ~/run

Когда будет изолирован первый плохой коммит, git bisect сообщит об этом:

ca4cfd28534303b82a216cfe83a1c80cbc3b9dc5 is first bad commit
commit ca4cfd28534303b82a216cfe83a1c80cbc3b9dc5
Author: Dave Mitchell <davem@fdisolutions.com>
Date:   Sat Feb 9 14:56:23 2008 +0000

    [perl #49472] Attributes + Unknown Error
    ...

bisect run success

Вы можете просмотреть процесс бисекции с помощью git bisect log и git bisect visualize. git bisect reset выведет вас из режима бисекции.

Обратите внимание, что первое good состояние должно быть предком первого bad состояния. Если вы хотите найти коммит, который исправил какую-то ошибку, вам нужно инвертировать ваш тестовый случай (т.е. завершить с 1 если все в порядке и 0 если нет) и по-прежнему указать нижнюю границу как good и верхнюю как bad. Тогда «первый плохой коммит» следует понимать как «первый коммит, где ошибка была решена».

git help bisect содержит гораздо больше информации о том, как можно настроить двоичные поиски.

После бисекции вы можете настроить, скомпилировать и протестировать perl в коммитах, определённых процессом бисекции. Иногда, особенно с более старыми версиями perl, make может завершиться неудачно. В этом случае вы можете исправить исходный код в точке старого коммита. Для этого следуйте инструкциям, предоставленным в "Building perl at older commits" в perlhack.

Тема ветвей и переписывание истории

Индивидуальные коммитеры должны создавать ветки тем под yourname/some_descriptive_name:

% branch="$yourname/$some_descriptive_name"
% git checkout -b $branch
... do local edits, commits etc ...
% git push origin -u $branch

Если вы работаете со старой версией git (до 1.7), то git push не будет иметь переключатель -u, и вам необходимо заменить последний шаг следующей последовательностью:

% git push origin $branch:refs/heads/$branch
% git config branch.$branch.remote origin
% git config branch.$branch.merge refs/heads/$branch

Если вы хотите внести изменения в ветку темы другого человека, вы должны согласовать это с его создателем, прежде чем вносить какие-либо изменения в неё.

Иногда вы можете обнаружить, что исходный автор отредактировал историю ветки. Для этого есть много хороших причин. Иногда автор просто перебазирует ветку на более новую точку источника. Иногда автор может обнаружить ошибку в раннем коммите, которую он хотел исправить перед слиянием ветки с blead.

В настоящее время репозиторий master настроен на запрет слияний, не являющихся быстрыми переходами. Это означает, что ветки внутри не могут быть перебазированы и отправлены как единый шаг.

Единственный способ, которым вам когда-либо будет разрешено перебазировать или изменить историю отправленной ветки, заключается в её удалении и отправке как новой ветки под тем же именем. Пожалуйста, хорошо обдумайте это. Возможно, лучше последовательно переименовать ваши ветки, чтобы другим работающим с вами было легче перенести их локальные изменения на новую версию. (XXX: требуется объяснение).

Если вы хотите перебазировать личную ветку темы, вам необходимо удалить существующую ветку темы и отправить её как новую версию. Вы можете сделать это по следующей формуле (см. объяснение refspec в документации git push для получения подробностей) после перебазирования вашей ветки:

# first rebase
% git checkout $user/$topic
% git fetch
% git rebase origin/blead

# then "delete-and-push"
% git push origin :$user/$topic
% git push origin $user/$topic

ПРИМЕЧАНИЕ: на уровне репозитория запрещено удалять любые «основные» ветки. Это любые ветки, соответствующие m!^(blead|maint|perl)!. Любая попытка сделать это приведет к ошибке git, подобной этой:

% git push origin :blead
*** It is forbidden to delete blead/maint branches in this repository
error: hooks/update exited with error code 1
error: hook declined to update refs/heads/blead
To ssh://perl5.git.perl.org/perl
 ! [remote rejected] blead (hook declined)
 error: failed to push some refs to 'ssh://perl5.git.perl.org/perl'

В соответствии с политикой, мы не редактируем историю веток blead и maint-*. Если в коммит blead или maint-* прокралась опечатка (или что-то хуже), мы исправим её в другом коммите. Единственные типы обновлений, разрешенные в этих ветках, — это «быстрые переходы», где вся история сохраняется.

Аннотированные теги в каноническом репозитории perl.git никогда не будут удалены или изменены. Тщательно обдумайте, хотите ли вы отправить локальный тег в perl.git, прежде чем делать это. (Отправка простых тегов не разрешена.)

Графты

История perl содержит одну ошибку, которая не была обнаружена при преобразовании: в истории был записан мердж между blead и maint-5.10, которого на самом деле не было. Из-за особенностей git это невозможно исправить в общедоступном репозитории. Вы можете удалить этот неверный мердж локально, добавив следующую строку в ваш файл .git/info/grafts:

296f12bbbbaa06de9be9d09d3dcf8f4528898a49 434946e0cb7a32589ed92d18008aaa1d88515930

Эта строка графта особенно важна, если выполняется бисекция в области рассматриваемого «слияния».

Доступ для записи в репозиторий git

После получения доступа для записи вам необходимо изменить URL для удалённого сервера origin, чтобы разрешить отправку. Измените .git/config с помощью команды git-config(1):

% git config remote.origin.url git@github.com:Perl/perl5.git

Вы также можете установить имя пользователя и адрес электронной почты. Большинство людей делают это глобально в ~/.gitconfig, выполняя действия вроде:

% git config --global user.name "Ævar Arnfjörð Bjarmason"
% git config --global user.email avarab@gmail.com

Однако, если вы хотите переопределить это только для perl, выполните что-то вроде следующего в perl:

% git config user.email avar@cpan.org

Также можно оставить origin в качестве удаленного сервера git и добавить новый удалённый сервер для доступа по ssh:

% git remote add camel git@github.com:Perl/perl5.git

Это позволяет обновлять ваш локальный репозиторий, подключаясь к origin, что быстрее и не требует аутентификации, и отправлять ваши изменения обратно с помощью удаленного сервера camel:

% git fetch camel
% git push camel

Команда fetch просто обновляет camel refs, так как сами объекты должны быть получены при подключении к origin.

Работа с запросами на вытягивание Github

Запросы на вытягивание обычно исходят извне репозитория Perl/perl.git, поэтому если вы хотите протестировать или поработать с ним локально, обычное подключение git fetch из репозитория Perl/perl5.git его не получит.

Однако Github предоставляет механизм для извлечения запроса на вытягивание в локальную ветку. Они доступны на удалённых серверах Github под pull/, поэтому вы можете использовать git fetch pull/PRID/head:localname для создания локальной копии. Например, чтобы извлечь запрос на вытягивание 9999 в локальную ветку local-branch-name, запустите:

git fetch origin pull/9999/head:local-branch-name

и затем:

git checkout local-branch-name

Примечание: эта ветка не перебазирована на blead, поэтому вместо описанного выше перехода, вы можете использовать:

git rebase origin/blead local-branch-name

что перебазирует local-branch-name на blead и переходит к ней.

В качестве альтернативы, вы можете настроить удалённый сервер для получения всех запросов на вытягивание в качестве удалённых отслеживаемых веток. Для этого измените удалённый сервер в .git/config. Например, если ваш удалённый сервер github — origin, у вас будет:

[remote "origin"]
        url = git@github.com:/Perl/perl5.git
        fetch = +refs/heads/*:refs/remotes/origin/*

Добавьте строку для сопоставления удалённых веток запросов на вытягивание с удалёнными отслеживаемыми ветками:

[remote "origin"]
        url = git@github.com:/Perl/perl5.git
        fetch = +refs/heads/*:refs/remotes/origin/*
        fetch = +refs/pull/*/head:refs/remotes/origin/pull/*

и затем выполните подключение как обычно:

git fetch origin

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

Чтобы удалить эти удалённые отслеживаемые ветки, удалите добавленную выше строку и обновите список:

git fetch -p origin # or git remote prune origin

Принятие патча

Если вы получили файл патча, созданный в соответствии с указанной выше секцией, вы должны попробовать применить его.

Сначала нам нужно создать временную новую ветку для этих изменений и переключиться на неё:

% git checkout -b experimental

Патчи, отформатированные с помощью git format-patch, применяются с помощью git am:

% git am 0001-Rename-Leon-Brocard-to-Orange-Brocard.patch
Applying Rename Leon Brocard to Orange Brocard

Обратите внимание, что некоторые почтовые системы UNIX могут изменять текстовые вложения, содержащие 'From '. Это их исправит:

% perl -pi -e's/^>From /From /' \
                       0001-Rename-Leon-Brocard-to-Orange-Brocard.patch

Если предоставляется только сырой разностный файл, возможен и этот двухэтапный процесс:

% git apply bugfix.diff
% git commit -a -m "Some fixing" \
                           --author="That Guy <that.guy@internets.com>"

Теперь мы можем проверить изменения:

% git show HEAD
commit b1b3dab48344cff6de4087efca3dbd63548ab5e2
Author: Leon Brocard <acme@astray.com>
Date:   Fri Dec 19 17:02:59 2008 +0000

  Rename Leon Brocard to Orange Brocard

diff --git a/AUTHORS b/AUTHORS
index 293dd70..722c93e 100644
--- a/AUTHORS
+++ b/AUTHORS
@@ -541,7 +541,7 @@ Lars Hecking                 <lhecking@nmrc.ucc.ie>
 Laszlo Molnar                  <laszlo.molnar@eth.ericsson.se>
 Leif Huhn                      <leif@hale.dkstat.com>
 Len Johnson                    <lenjay@ibm.net>
-Leon Brocard                   <acme@astray.com>
+Orange Brocard                 <acme@astray.com>
 Les Peters                     <lpeters@aol.net>
 Lesley Binks                   <lesley.binks@gmail.com>
 Lincoln D. Stein               <lstein@cshl.org>

Если вы коммитер Perl и считаете, что патч хороший, вы можете затем слить его в blead и отправить его в основной репозиторий:

% git checkout blead
% git merge experimental
% git push origin blead

Если вы хотите удалить временную ветку, вы можете сделать это с помощью:

% git checkout blead
% git branch -d experimental
error: The branch 'experimental' is not an ancestor of your current
HEAD.  If you are sure you want to delete it, run 'git branch -D
experimental'.
% git branch -D experimental
Deleted branch experimental.

Добавление изменений в ветку blead

Ветка 'blead' станет следующей производственной версией Perl.

Перед отправкой любых локальных изменений в blead крайне важно сделать несколько вещей, чтобы избежать недовольства других коммитеров:

• Убедитесь, что у вас есть хорошее сообщение коммита. См. "Commit message" в perlhack для получения подробностей.

• Запустите набор тестов. Вы, возможно, не думаете, что одно исправление опечатки повлияет на файлы тестов. Вы ошибаетесь. Вот пример того, как проблемы возникли из-за того, что набор тестов не был запущен. Был отправлен патч, добавивший несколько тестов в существующий файл .t. Вероятно, это не повлияет на что-либо ещё, так что нет необходимости проверять что-либо кроме затронутого файла .t, верно? Но адрес электронной почты отправителя изменился с момента последнего его отправления, и это привело к сбоям в других тестах. Запуск тестовой цели, указанной в следующем пункте, позволил бы обнаружить эту проблему.

• Если вы не запускаете полный набор тестов, по крайней мере, запустите make test_porting. Это выполнит основные проверки работоспособности. Чтобы узнать, какие проверки работоспособности, посмотрите в t/porting.

• Если вы вносите какие-либо изменения, затрагивающие miniperl или ядровых функций, которые имеют разные пути кода для miniperl, обязательно запустите make minitest. Это позволит обнаружить проблемы, которые даже полный набор тестов не обнаружит, потому что он выполняет подмножество тестов в miniperl, а не в perl.

О слиянии и перебазировании

Простые разовые коммиты, отправленные в ветку 'blead', должны быть простыми коммитами, которые применяются корректно. Другими словами, вы должны убедиться, что ваша работа оформляется как коммит относительно текущего состояния blead, так чтобы вы могли отправить свои изменения в основной репозиторий без слияния.

Иногда blead будет перемещаться, пока вы строили или тестировали свои изменения. В этом случае ваша отправка будет отклонена с сообщением подобным этому:

To ssh://perl5.git.perl.org/perl.git
 ! [rejected]        blead -> blead (non-fast-forward)
error: failed to push some refs to 'ssh://perl5.git.perl.org/perl.git'
To prevent you from losing history, non-fast-forward updates were
rejected Merge the remote changes (e.g. 'git pull') before pushing
again.  See the 'Note about fast-forwards' section of 'git push --help'
for details.

В этом случае вы можете просто перебазировать свою работу относительно нового состояния blead, например так (предполагая, что ваш удалённый сервер для основного репозитория — «p5p»):

% git fetch p5p
% git rebase p5p/blead

Вы увидите, как ваши коммиты повторно применяются, и тогда сможете безопасно выполнить push. Более подробную информацию о ребейзинге можно найти в документации к команде git-rebase(1).

Для больших наборов коммитов, которые имеют смысл только вместе или которые могли бы выиграть от резюме цели набора, вы должны использовать коммит слияния. Вы должны выполнять свою работу на ветви темы, которую вы должны регулярно ребейзить относительно blead, чтобы убедиться, что ваш код не сломался из-за перемещения blead. Когда вы закончите свою работу, выполните финальный ребейз и тестирование. Линейная история теряется с каждым коммитом на blead, но финальный ребейз делает историю линейной снова, что упрощает будущим разработчикам увидеть, что произошло. Выполните ребейз следующим образом (предполагая, что ваша работа велась на ветви committer/somework):

% git checkout committer/somework
% git rebase blead

Затем вы можете объединить его в master так:

% git checkout blead
% git merge --no-ff --no-commit committer/somework
% git commit -a

Вышеперечисленные переключатели заслуживают объяснения. --no-ff указывает, что даже если вся ваша работа может быть применена линейно к blead, всё равно следует подготовить коммит слияния. Это гарантирует, что вся ваша работа будет отображаться как отдельная ветвь, слияние всех ее коммитов в основную ветвь blead с помощью коммита слияния.

--no-commit означает, что коммит слияния будет подготовлен, но не зафиксирован. Затем коммит фактически выполняется при выполнении следующей команды, которая откроет ваш редактор для описания коммита. Без --no-commit, коммит был бы создан практически без полезного сообщения, что значительно уменьшило бы ценность коммита слияния как заготовки для описания работы.

При описании коммита слияния объясните цель ветви, и помните, что это описание, вероятно, будет использовано инженером по выпуску при просмотре следующего документа perldelta.

Фиксация изменений в версиях поддержки

Версии поддержки должны изменяться только для добавления критических исправлений ошибок, см. perlpolicy.

Для фиксации изменений в поддерживаемой версии perl вам необходимо создать локальную ветвь отслеживания:

% git checkout --track -b maint-5.005 origin/maint-5.005

Это создаёт локальную ветвь с именем maint-5.005, которая отслеживает удалённую ветвь origin/maint-5.005. Затем вы можете выполнить pull, commit, merge и push, как и прежде.

Вы также можете использовать команду git cherry-pick, чтобы выбрать коммиты из blead и другой ветви. Рекомендуется использовать опцию -x для git cherry-pick, чтобы записать SHA1 исходного коммита в сообщение нового коммита.

Перед отправкой любых изменений в версию поддержки убедитесь, что вы выполнили шаги в "Фиксация изменений в blead" выше.

Использование ветви smoke-me для тестирования изменений

Иногда изменение затрагивает пути кода, которые вы не можете протестировать на ОС, которые вам непосредственно доступны, и было бы разумно, чтобы пользователи других ОС протестировали изменение до того, как вы зафиксируете его в blead.

К счастью, есть способ получить тестирование изменений на различных ОС: отправьте его на ветвь "smoke-me" и дождитесь отчетов от автоматизированных тестировщиков с разных ОС. Ветвь "smoke-me" определяется именем ветви: в частности, как видно на github.com, это должна быть локальная ветвь, у которой первый компонент имени точно smoke-me.

Процедура примерно следующая (на примере ветви smoke-me tonyc под названием win32stat):

Сначала создайте локальную ветвь и переключитесь на неё:

% git checkout -b win32stat

Внесите изменения, скомпилируйте perl и протестируйте свои изменения, затем зафиксируйте их в вашей локальной ветви. Затем отправьте вашу локальную ветвь на удалённую ветвь smoke-me:

% git push origin win32stat:smoke-me/tonyc/win32stat

Теперь вы можете переключиться обратно на blead локально:

% git checkout blead

и продолжить работу над другими задачами, в течение дня или двух, следя за результатами, которые сообщаются для вашей ветви smoke-me по адресу http://perl.develop-help.com/?b=smoke-me/tonyc/win32state.

Если всё в порядке, обновите свою ветвь blead:

% git pull

затем снова переключитесь на свою ветвь smoke-me и выполните ребейз на blead:

% git rebase blead win32stat

Теперь переключитесь обратно на blead и объедините свою ветвь smoke-me с ней:

% git checkout blead
% git merge win32stat

Как описано ранее, если у вашей ветви smoke-me много изменений, то вы должны подготовить коммит слияния, в котором даётся общий обзор этих изменений, используя следующую команду вместо последней команды выше:

% git merge win32stat --no-ff --no-commit

Теперь вы должны скомпилировать perl и в последний раз проверить ваши (объединённые) изменения (в идеале запустить весь набор тестов, но если это не так, то по крайней мере запустите тесты t/porting/*.t) перед отправкой ваших изменений обычным образом:

% git push origin blead

Наконец, вы должны удалить удалённую ветвь smoke-me:

% git push origin :smoke-me/tonyc/win32stat

(что, вероятно, выведет предупреждение, которое можно проигнорировать:

remote: fatal: ambiguous argument
                                 'refs/heads/smoke-me/tonyc/win32stat':
unknown revision or path not in the working tree.
remote: Use '--' to separate paths from revisions

) и затем удалить свою локальную ветвь:

% git branch -d win32stat