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

У вас уже есть собственная вилка репозитория 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; однако, это может добавить нежелательные изменения в коммит, если вы не будете внимательны. Для получения дополнительной информации см. why the -a flag? — и полезное описание варианта использования в tangled working copy problem.

6. Отправьте изменения в свой разветвлённый репозиторий на github:

   git push origin my-new-feature
   

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

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

git push

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

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

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

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.

Перебазирование на мастер

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

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

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

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

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 couple 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

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

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

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.

Когда у вас есть набор «готовых» изменений в ветке функции, готовых для веток NumPy master или maintenance, вы можете отправить их в 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