Процесс разработки

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

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

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

git fetch upstream

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

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

git push origin my-new-feature

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

git push

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.

Получение мнения списка рассылки

Если вы планируете новую функцию или изменение API, разумнее всего сначала отправить электронное письмо на список рассылки NumPy почта рассылки, чтобы запросить комментарии. Если вы не получите ответа в течение недели, можете снова отправить письмо на список рассылки.

Запрос на слияние ваших изменений с основным репозиторием

Когда вы закончите работу, вы можете создать запрос на слияние (PR). Если ваши изменения включают изменения API или добавление/модификацию функции, добавьте заметку о выпуске в каталог v в соответствии с инструкциями и форматом в файле doc/release/upcoming_changes/.

Рассмотрение вашего запроса на слияние

Мы рассматриваем запросы на слияние как можно скорее, обычно в течение недели. Если вы не получите комментариев к вашему запросу на слияние в течение двух недель, смело запросите обратную связь, добавив комментарий к запросу на слияние (это уведомит ответственных лиц).

Если ваш запрос на слияние большой или сложный, запросить отзывы на списке рассылки numpy-discussion может быть полезно.

Слияние с веткой main

Это обновляет вашу ветку функции изменениями из репозитория 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 main branch
git rebase upstream/main

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

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

git branch -D tmp

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

Иногда вы совершаете ошибки при слияниях или слияниях с веткой main. К счастью, в 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 — последний коммит в ветке main. Предположим, что мы хотим внести следующие изменения:

• Переписать сообщение коммита для 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 main
# delete branch locally
git branch -D my-unwanted-branch
# delete branch on github
git push origin --delete my-unwanted-branch

См. также: https://stackoverflow.com/questions/2003505/how-do-i-delete-a-git-branch-locally-and-remotely

Несколько человек, разделяющих один репозиторий

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

Сначала создайте форк NumPy в своей учетной записи, как в Создании собственной копии (форка) scikit-image.

Затем перейдите на страницу вашего форкнутого репозитория на 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

Получение изменений из существующего запроса на вытягивание

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

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

Затем, получите изменения и создайте локальную ветку. Предполагая, что $ID — номер запроса на вытягивание, а $BRANCHNAME — имя новой локальной ветки, которую вы хотите создать:

git fetch upstream pull/$ID/head:$BRANCHNAME

Переключитесь на только что созданную ветку:

git checkout $BRANCHNAME

Теперь у вас есть изменения в запросе на вытягивание.

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

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

gitk --all

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

git log

Бэкпортирование

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

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

   # 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. Теперь вам нужно применить изменения из main в эту ветку, используя git cherry-pick:

   # Update remote
   git fetch upstream
   # Check the commit log for commits to cherry pick
   git log upstream/main
   # 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. Вы можете столкнуться с некоторыми конфликтами при выборе коммитов. Они решаются так же, как и конфликты при слиянии/слиянии с веткой main. За исключением того, что здесь вы можете использовать git blame для сравнения различий между main и бэкпортированной веткой, чтобы убедиться, что ничего не сломано.

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

   git push -u origin backport-3324
   

5. Наконец, создайте запрос на вытягивание с помощью GitHub. Убедитесь, что это запрос на вытягивание против ветки сопровождения, а не main, GitHub обычно предложит вам сделать запрос на вытягивание против main.

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

Требуются права на коммит в основной репозиторий NumPy.

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

1. Сначала объедините или слийте изменения с целевой веткой.

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

      git fetch upstream
      git rebase upstream/main
      

      См. Слияние с веткой main.

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

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

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

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

3. Отправьте изменения в upstream:

   git push upstream my-feature-branch:main