perlgit

СОДЕРЖАНИЕ

НАЗВАНИЕ
ОПИСАНИЕ
КЛОНИРОВАНИЕ РЕПОЗИТОРИЯ
РАБОТА С РЕПОЗИТОРИЕМ
ДОСТУП НА ЗАПИСЬ В РЕПОЗИТОРИЙ GIT

НАЗВАНИЕ

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

ОПИСАНИЕ

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

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

Весь исходный код Perl хранится централизованно в репозитории Git по адресу perl5.git.perl.org.

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

% git clone git://perl5.git.perl.org/perl.git perl

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

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

% git clone http://perl5.git.perl.org/perl.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 для более линейной истории. Если вы не работаете с ветвью темы, разработчику необходимо вручную выполнить cherry-pick ваших изменений в blead, прежде чем их можно будет применить.

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

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

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

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

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

   modified:   AUTHORS

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

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

Теперь сохраните изменения локально:

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

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

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

После завершения написания сообщения коммита и выхода из редактора 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

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

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

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

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

Теперь вы должны отправить электронное письмо на адрес perlbug@perl.org с описанием своих изменений и включить этот файл патча в качестве вложения. В дополнение к отслеживанию в RT, почта на perlbug будет автоматически пересылаться на perl5-porters (с ручной модерацией, поэтому, пожалуйста, будьте терпеливы). Вы должны отправлять патчи непосредственно на perl5-porters@perl.org только если патч не готов к применению, но предназначен для обсуждения.

Пожалуйста, не используйте git-send-email(1) для отправки своего патча. Более подробную информацию см. в разделе Отправка писем с патчами.

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

% 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 commit -a

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

Git запустит ваш любимый текстовый редактор, чтобы вы могли составить сообщение коммита для вашего изменения. Более подробную информацию о создании хорошего сообщения коммита см. в разделе "Сообщение коммита" в perlhack.

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

Если вы повторно запустите git status, вы увидите примерно следующее:

% git status
On branch blead
Your branch is ahead of 'origin/blead' by 2 commits.
  (use "git push" to publish your local commits)
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.

Отправка писем с патчами

После того, как вы сгенерировали свой патч, вы должны отправить его на адрес perlbug@perl.org (как обсуждалось в предыдущем разделе) с помощью обычного почтового клиента в качестве вложения, а также с описанием патча.

Вы не должны использовать git-send-email(1) для отправки патчей, сгенерированных с помощью git-format-patch(1). Система отслеживания проблем RT, стоящая за perlbug@perl.org, не учитывает содержимое электронных писем. Отправка патча в тексте электронного письма гарантирует, что ваш патч будет удалён.

END_OF_DOCUMENT_MARKER

Кто-то может загрузить ваш патч из RT, что приведет к опущению темы (первой строки сообщения с изменениями). См. RT #74192 и commit a4583001 для примера. В качестве альтернативы кто-то может применить ваш патч из RT после его получения в почтовом ящике, к тому времени как RT изменит встроенное содержимое сообщения. См. RT #74532 и commit f9bcfeac для плохого примера такого сбоя.

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

Обратите внимание, что многие файлы в дистрибутиве являются производными — избегайте их патчинга, потому что 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 был записан merge, которого на самом деле не было. Из-за особенностей git это невозможно исправить в публичном репозитории. Вы можете удалить это неверное слияние локально, добавив следующую строку в свой файл .git/info/grafts:

296f12bbbbaa06de9be9d09d3dcf8f4528898a49 434946e0cb7a32589ed92d18008aaa1d88515930

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

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

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

% git config remote.origin.url ssh://perl5.git.perl.org/perl.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 perl5.git.perl.org:/perl.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

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

% 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

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

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

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

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

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

Фиксация в версиях обслуживания

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

Чтобы зафиксировать изменения в версии обслуживания perl, необходимо создать локальную отслеживающую ветвь:

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

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

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

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

Слияние из ветки через GitHub

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

% git remote add avar git://github.com/avar/perl.git
% git fetch avar

Теперь вы можете увидеть различия между веткой и blead:

% git diff avar/orange

И вы можете увидеть коммиты:

% git log avar/orange

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

% git cherry-pick 0c24b290ae02b2ab3304f51d5e11e85eb3659eae

Или вы можете просто слить всю ветку, если хотите всё:

% git merge avar/orange

И затем отправить обратно в репозиторий:

% git push origin blead

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

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

К счастью, есть способ проверить ваше изменение на различных ОС: отправьте его в ветку "smoke-me" и подождите, пока определённые автоматические тестеры сообщат результаты с их ОС. Ветка "smoke-me" определяется по имени ветки: в частности, как видно на perl5.git.perl.org, это должна быть локальная ветка, первым компонентом имени которой является именно 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

Примечание о верблюде и дромедаре

Разработчики имеют доступ по SSH к двум серверам, которые обслуживают perl5.git.perl.org. Один из них — сам perl5.git.perl.org (верблюд), который является основным репозиторием. Второй — users.perl5.git.perl.org (дромадер), который можно использовать для общего тестирования и разработки. Дромадер синхронизирует дерево git с верблюдом каждые несколько минут, поэтому не следует отправлять туда. На обоих машинах также есть полный зеркало CPAN в /srv/CPAN, пожалуйста, используйте его. Для обмена файлами с широкой публикой, дромадер использует ваш ~/public_html/ как http://users.perl5.git.perl.org/~yourlogin/

На этих хостах довольно жёсткие брандмауэры для внешнего доступа. Внешний доступ разрешен только для rsync, ssh и git. Для http и ftp вы можете использовать http://webproxy:3128 в качестве прокси. Внутренний доступ брандмауэр пытается обнаружить атаки и блокирует IP-адреса с подозрительной активностью. Иногда (но очень редко) возникают ложноположительные результаты, и вы можете быть заблокированы. Самый быстрый способ разблокировки — уведомить администраторов.

Эти два узла принадлежат, размещаются и управляются booking.com. Вы можете связаться с системными администраторами в #p5p на irc.perl.org или по электронной почте perl5-porters@perl.org.

© 1993–2020 Larry Wall and others
Licensed under the GNU General Public License version 1 or later, or the Artistic License.
The Perl logo is a trademark of the Perl Foundation.
https://perldoc.perl.org/5.28.3/perlgit