Поток разработки

У вас уже есть своя вилка репозитория NumPy, созданная, следуя созданию своей копии (вилки) NumPy, настройке вашей вилки, вы настраивали git, следуя настройке Git, и связали репозиторий с исходным, как описано в связывании вашего репозитория с исходным.

Ниже описан рекомендуемый поток работы с Git.

Основной поток работы

Вкратце:

1. Для каждой серии изменений начинайте новую ветвь функций. Смотрите ниже.
2. Начинайте работу! Смотрите ниже

3. По завершении:

   • Авторы: опубликуйте свою ветвь функций в вашем репозитории на Github и создайте запрос на объединение.
   • Главные разработчики Если вы хотите опубликовать изменения без дальнейшего обсуждения, смотрите заметки ниже.

Такой способ работы помогает поддерживать четкую структуру работы и историю.

Создание новой ветви функций

Сначала получите новые коммиты из репозитория upstream:

git fetch upstream

Затем создайте новую ветвь, основанную на ветви master исходного репозитория:

git checkout -b my-new-feature upstream/master

Поток редактирования

Обзор

# hack hack
git status # Optional
git diff # Optional
git add modified_file
git commit
# push the branch to your own Github repo
git push origin my-new-feature

Подробности

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

2. Необязательно: Проверьте, какие файлы были изменены с помощью git status (см. git status). Вы увидите список, похожий на этот:

   # On branch my-new-feature
   # Changed but not updated:
   #   (use "git add <file>..." to update what will be committed)
   #   (use "git checkout -- <file>..." to discard changes in working directory)
   #
   #  modified:   README
   #
   # Untracked files:
   #   (use "git add <file>..." to include in what will be committed)
   #
   #  INSTALL
   no changes added to commit (use "git add" and/or "git commit -a")
   

3. Необязательно: Сравните изменения с предыдущей версией с помощью git diff (git diff). Это откроет простую текстовую оболочку, которая выделит разницу между вашими файлами и предыдущей версией.
4. Добавьте все соответствующие измененные или новые файлы, используя git add modified_file (см. git add). Это поместит файлы в область подготовки, которая является очередью файлов, которые будут добавлены к следующему коммиту. Добавляйте только файлы с завершенными взаимосвязанными изменениями. Оставляйте файлы с незавершенными изменениями для последующих коммитов.

5. Чтобы сохранить подготовленные файлы в локальной копии репозитория, выполните git commit. На этом этапе откроется текстовый редактор, чтобы вы могли написать сообщение коммита. Прочитайте раздел сообщение коммита, чтобы убедиться, что вы пишете сообщение коммита в правильном формате и с достаточной детализацией. После сохранения сообщения и закрытия редактора ваш коммит будет сохранен. Для тривиальных коммитов короткое сообщение коммита может быть передано через командную строку с флагом -m . Например, git commit -am "ENH: Some message".

   В некоторых случаях вы увидите эту форму команды коммита: git commit -a. Дополнительный флаг -a автоматически коммитит все измененные файлы и удаляет все удаленные файлы. Это может сэкономить вам написание многочисленных команд git add; однако, это может добавить нежелательные изменения в коммит, если вы не будете осторожны. Для получения дополнительной информации см. почему флаг -a? - и полезное описание использования в проблеме запутанной рабочей копии.

6. Опубликуйте изменения в ваш вилоченный репозиторий на github:

   git push origin my-new-feature
   

   Для получения дополнительной информации см. git push.

git push --set-upstream origin my-new-feature

git push

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

Создание сообщения коммита

Сообщения коммитов должны быть понятными и следовать нескольким основным правилам. Пример:

ENH: add functionality X to numpy.<submodule>.

The first line of the commit message starts with a capitalized acronym
(options listed below) indicating what type of commit this is.  Then a blank
line, then more text if needed.  Lines shouldn't be longer than 72
characters.  If the commit is related to a ticket, indicate that with
"See #3456", "See ticket 3456", "Closes #3456" or similar.

Описание мотивации изменения, характера ошибки для исправления ошибок или некоторых подробностей об улучшениях также полезно включить в сообщение коммита. Сообщения должны быть понятны без просмотра изменений кода. Сообщение коммита, подобное MAINT: fixed another one, является примером того, чего делать не следует; читателю необходимо искать контекст в другом месте.

Стандартные аббревиатуры для начала сообщения коммита:

API: an (incompatible) API change
BENCH: changes to the benchmark suite
BLD: change related to building numpy
BUG: bug fix
DEP: deprecate something, or remove a deprecated object
DEV: development tool or utility
DOC: documentation
ENH: enhancement
MAINT: maintenance commit (refactoring, typos, etc.)
REV: revert an earlier commit
STY: style fix (whitespace, PEP8)
TST: addition or modification of tests
REL: related to releasing numpy

Запрос на объединение изменений с основным репозиторием

Когда вы закончите работу, вы можете создать запрос на объединение (PR). Github имеет хорошую страницу справки, которая описывает процесс создания запросов на объединение.

Если ваши изменения связаны с модификациями API или добавлением/модификацией функции, вы должны

• отправить электронное письмо на список рассылки NumPy со ссылкой на ваш PR вместе с описанием и мотивацией ваших изменений. Это может породить изменения и отзывы. Возможно, целесообразно начать с этого шага, если ваше изменение может быть спорным.
• добавить заметку о выпуске в каталог doc/release/upcoming_changes/, следуя инструкциям и формату в файле doc/release/upcoming_changes/README.rst.

Перебазирование на master

Это обновляет вашу ветвь функций с изменениями из репозитория NumPy github. Если вы не обязаны это делать, старайтесь этого избегать, разве что, возможно, когда вы закончите. Первый шаг — обновить удаленный репозиторий новыми коммитами из исходного:

git fetch upstream

Далее, вам нужно обновить ветвь функций:

# go to the feature branch
git checkout my-new-feature
# make a backup in case you mess up
git branch tmp my-new-feature
# rebase on upstream master branch
git rebase upstream/master

Если вы внесли изменения в файлы, которые также были изменены в исходном репозитории, это может создать конфликты слияния, которые вам нужно разрешить. См. раздел восстановление после ошибок для помощи в этом случае.

Наконец, удалите резервную ветвь после успешного перебазирования:

git branch -D tmp

Восстановление после ошибок

Иногда вы ошибаетесь при слияниях или перебазировании. К счастью, в Git относительно просто исправить такие ошибки.

Если вы ошиблись во время перебазирования:

git rebase --abort

Если вы заметили ошибку после перебазирования:

# reset branch back to the saved point
git reset --hard tmp

Если вы забыли создать резервную ветвь:

# look at the reflog of the branch
git reflog show my-feature-branch

8630830 my-feature-branch@{0}: commit: BUG: io: close file handles immediately
278dd2a my-feature-branch@{1}: rebase finished: refs/heads/my-feature-branch onto 11ee694744f2552d
26aa21a my-feature-branch@{2}: commit: BUG: lib: make seek_gzip_factory not leak gzip obj
...

# reset the branch to where it was before the botched rebase
git reset --hard my-feature-branch@{2}

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

Дополнительные действия, которые вы можете выполнить

Переписывание истории коммитов

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

Это можно сделать с помощью интерактивного перебазирования.

Предположим, что история коммитов выглядит так:

git log --oneline
eadc391 Fix some remaining bugs
a815645 Modify it so that it works
2dec1ac Fix a few bugs + disable
13d7934 First implementation
6ad92e5 * masked is now an instance of a new object, MaskedConstant
29001ed Add pre-nep for a copule of structured_array_extensions.
...

и 6ad92e5 — последний коммит в ветви master. Предположим, что мы хотим внести следующие изменения:

• Переписать сообщение коммита для 13d7934 на что-то более осмысленное.
• Объединить коммиты 2dec1ac, a815645, eadc391 в один.

Мы делаем следующее:

# make a backup of the current state
git branch tmp HEAD
# interactive rebase
git rebase -i 6ad92e5

Это откроет редактор с следующим текстом:

pick 13d7934 First implementation
pick 2dec1ac Fix a few bugs + disable
pick a815645 Modify it so that it works
pick eadc391 Fix some remaining bugs

# Rebase 6ad92e5..eadc391 onto 6ad92e5
#
# Commands:
#  p, pick = use commit
#  r, reword = use commit, but edit the commit message
#  e, edit = use commit, but stop for amending
#  s, squash = use commit, but meld into previous commit
#  f, fixup = like "squash", but discard this commit's log message
#
# If you remove a line here THAT COMMIT WILL BE LOST.
# However, if you remove everything, the rebase will be aborted.
#

Чтобы достичь того, что мы хотим, мы внесем следующие изменения:

r 13d7934 First implementation
pick 2dec1ac Fix a few bugs + disable
f a815645 Modify it so that it works
f eadc391 Fix some remaining bugs

Это означает, что (i) мы хотим отредактировать сообщение о коммите для 13d7934, и (ii) объединить последние три коммита в один. Теперь мы сохраняем и выходим из редактора.

Git немедленно откроет редактор для изменения сообщения о коммите. После его пересмотра мы получим вывод:

[detached HEAD 721fc64] FOO: First implementation
 2 files changed, 199 insertions(+), 66 deletions(-)
[detached HEAD 0f22701] Fix a few bugs + disable
 1 files changed, 79 insertions(+), 61 deletions(-)
Successfully rebased and updated refs/heads/my-feature-branch.

и история теперь выглядит следующим образом:

0f22701 Fix a few bugs + disable
721fc64 ENH: Sophisticated feature
6ad92e5 * masked is now an instance of a new object, MaskedConstant

Если что-то пошло не так, восстановление снова возможно, как описано выше.

Удаление ветки на github

git checkout master
# delete branch locally
git branch -D my-unwanted-branch
# delete branch on github
git push origin :my-unwanted-branch

(Обратите внимание на двоеточие : перед test-branch. См. также: https://github.com/guides/remove-a-remote-branch

Несколько человек используют один репозиторий

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

Сначала разделите NumPy на свою учётную запись, как из создание собственной копии (разделение) NumPy.

Затем перейдите на страницу вашего разветвлённого репозитория github, например, https://github.com/your-user-name/numpy

Нажмите кнопку «Администрирование» и добавьте других людей в репозиторий в качестве соавторов:

Теперь все эти люди могут:

git clone git@github.com:your-user-name/numpy.git

Помните, что ссылки, начинающиеся с git@, используют протокол ssh и являются чтением/записью; ссылки, начинающиеся с git://, являются только для чтения.

Затем ваши соавторы могут делать коммиты непосредственно в этот репозиторий с помощью обычных команд:

git commit -am 'ENH - much better code'
git push origin my-feature-branch # pushes directly into your repo

Обзор вашего репозитория

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

gitk --all

Чтобы увидеть линейный список коммитов для этой ветки:

git log

Вы также можете посмотреть на визуализатор сетевых графиков для вашего репозитория на github.

Обратная портирование

Обратная портирование — это процесс копирования новых функций/исправлений, внесённых в numpy/master, обратно в стабильные ветки выпусков. Для этого вы создаёте ветку от ветки, в которую вы портируете, выбираете нужные коммиты из numpy/master, а затем отправляете запрос на включение ветки с обратной портированием.

1. Сначала вам нужно создать ветку, над которой вы будете работать. Она должна основываться на более старой версии NumPy (не на master):

   # Make a new branch based on numpy/maintenance/1.8.x,
   # backport-3324 is our new name for the branch.
   git checkout -b backport-3324 upstream/maintenance/1.8.x
   

2. Теперь вам нужно применить изменения из master к этой ветке, используя git cherry-pick:

   # Update remote
   git fetch upstream
   # Check the commit log for commits to cherry pick
   git log upstream/master
   # This pull request included commits aa7a047 to c098283 (inclusive)
   # so you use the .. syntax (for a range of commits), the ^ makes the
   # range inclusive.
   git cherry-pick aa7a047^..c098283
   ...
   # Fix any conflicts, then if needed:
   git cherry-pick --continue
   

3. При применении cherry-pick вы можете столкнуться с конфликтами. Они решаются так же, как конфликты при слиянии/перебазировании. За исключением того, что здесь вы можете использовать git blame, чтобы увидеть разницу между master и веткой обратной портирования, чтобы убедиться, что ничего не сломано.

4. Отправьте новую ветку в свой репозиторий на Github:

   git push -u origin backport-3324
   

5. Наконец, создайте запрос на включение, используя Github. Убедитесь, что он направлен на ветку обслуживания, а не на master. Github обычно предложит создать запрос на включение по отношению к master.

Отправка изменений в основной репозиторий

Это актуально только в том случае, если у вас есть права на коммиты в основной репозиторий NumPy.

Когда у вас есть набор «готовых» изменений в ветке функции, готовых для master или maintenance ветвей NumPy, вы можете отправить их в upstream следующим образом:

1. Сначала слить или перебазировать на целевую ветку.

   1. Только несколько несвязанных коммитов, затем предпочтительно перебазирование:

      git fetch upstream
      git rebase upstream/master
      

      См. Перебазирование на master.

   2. Если все коммиты связаны, создайте коммит слияния:

      git fetch upstream
      git merge --no-ff upstream/master
      

2. Проверьте, что то, что вы собираетесь отправить, выглядит осмысленно:

   git log -p upstream/master..
   git log --oneline --graph
   

3. Отправить на upstream:

   git push upstream my-feature-branch:master