perlgit

СОДЕРЖАНИЕ

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

ИМЯ

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

ОПИСАНИЕ

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

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

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

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

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

Это использует протокол git (порт 9418).

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

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

% 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

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

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

И отправьте ветку в свой форк:

% git push -u fork orange

Теперь вы должны отправить запрос на вытягивание (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" in 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 это невозможно исправить в публичном репозитории. Вы можете удалить этот ошибочный мердж локально, добавив следующую строку в свой файл .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

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

% git fetch camel
% git push camel

Команда fetch просто обновляет camel refs, так как сами объекты должны были быть получены при выполнении pull из 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/*

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

git fetch origin

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

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

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" in 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

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

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

% git checkout committer/somework
% git rebase blead

Затем вы можете слить её в мастер, так:

% 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, фиксацию, слияние и push, как и прежде.

Вы также можете выбрать коммиты из blead и другой ветки, используя команду git cherry-pick. Рекомендуется использовать опцию -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