perlgit

СОДЕРЖАНИЕ

• ИМЯ
• ОПИСАНИЕ
• КЛОНИРОВАНИЕ РЕПОЗИТОРИЯ
• РАБОТА С РЕПОЗИТОРИЕМ
  • Определение вашего статуса
  • Процесс работы с патчами
  • Примечание о производных файлах
  • Очистка рабочей директории
  • Бисекция
  • Ветви тем и переписывание истории
  • Вставки
• ДОСТУП НА ЗАПИСЬ В РЕПОЗИТОРИЙ GIT
  • Принятие патча
  • Зафиксировать изменения в 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, поскольку именно здесь происходит разработка новых изменений, кроме критических исправлений ошибок. Критические исправления ошибок должны создаваться на соответствующих ветвях поддержки или должны быть представлены с примечанием, указывающим все ветви, в которых исправление должно быть применено.

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

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

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

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

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

% 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

Вы увидите, что ваши коммиты будут повторно применены, и тогда вы сможете безопасно опубликовать их. Дополнительную информацию о перебазировании можно найти в документации к команде 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