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

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

% 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, так как именно там происходит разработка новых изменений, за исключением критических исправлений ошибок. Критические исправления ошибок должны выполняться на соответствующих ветках поддержки или должны быть представлены с заметкой, указывающей все ветки, в которых исправление должно быть применено.

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

% git checkout -b orange

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

% git branch orange
% git checkout orange

Создание ветки темы упрощает для разработчиков перебазирование или слияние обратно в основную ветку blead для более линейной истории. Если вы не работаете в ветке темы, разработчику приходится вручную выбирать ваши изменения в ветку 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 символов. См. "Commit message" в 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 самостоятельно. Наиболее полезно использовать git bisect run для автоматизации сборки и тестирования ревизий 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.

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

Единственный способ, которым вы сможете перебазировать или изменить историю отправленной ветки, — это удалить её и отправить как новую ветку с тем же именем. Пожалуйста, хорошо подумайте, прежде чем делать это. Возможно, лучше последовательно переименовать ваши ветки, чтобы другим пользователям, работающим с вами, было легче подбирать свои локальные изменения к новой версии. (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 это невозможно исправить в общедоступном репозитории. Вы можете удалить это неверное слияние локально, добавив следующую строку в свой файл %%%CODE_BLOCK_127%%:

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 ссылки, так как сами объекты должны были быть получены при подтягивании данных из 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

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

% 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.

Если последующий push завершится ошибкой, необходимо быть внимательными при слиянии. Если вы используете

% git rebase p5p/blead

или

% git pull --rebase

то ваш тщательно созданный коммит слияния будет утерян! Чтобы этого избежать, можно использовать:

% git fetch p5p
% git rebase --rebase-merges p5p/blead

Это позволит восстановить ваш коммит слияния.

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

Фиксация изменений в версиях технического обслуживания

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

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

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

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

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

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

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

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

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

Процедура выполнения примерно следующая (с использованием примера ветви smoke-me тониcа под названием 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