Spec-Zone.ru › NumPy 1.21

Рабочий процесс разработки

У вас уже есть своя вилка репозитория NumPy, созданная, следуя инструкциям Создание вилки NumPy, Создание локальной копии. Вы настроите git, следуя инструкциям Настройка Git, и связали репозиторий с родительским репозиторием, как описано в Связывание вашего репозитория с родительским репозиторием.

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

Основной рабочий процесс

Кратко:

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

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

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

См. также

Существует множество онлайн-учебников, которые помогут вам изучить git. Для обсуждения конкретных рабочих процессов git см. эти обсуждения в linux git workflow и ipython git workflow.

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

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

git fetch upstream

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

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

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

Обзор

# 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 создаст по умолчанию ссылку на ваш репозиторий на github под названием origin. В git >= 1.7 вы можете гарантировать, что ссылка на origin будет постоянно установлена, используя параметр --set-upstream:

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

Отныне git будет знать, что my-new-feature относится к ветке my-new-feature в вашем собственном репозитории на github. Последующие вызовы push упрощаются до следующего:

git push

Вы должны использовать --set-upstream для каждой новой ветви, которую вы создаете.

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

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

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

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

Получение отзывов от списка рассылки

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

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

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

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

Обзор запросов на слияние (PR)

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

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

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

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

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

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

git branch -D tmp

Примечание

Перебазирование на main предпочтительнее слияния родительского репозитория обратно в вашу ветвь. Использование git merge и git pull не рекомендуется при работе с ветвями функций.

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

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

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

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

../_images/pull_button.png

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

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/main, обратно во стабильные ветки выпусков. Для этого вы создаете ветку из ветки, в которую бэкпортите, выбираете нужные коммиты из 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. При бэкпортировании могут возникнуть конфликты. Они разрешаются так же, как конфликты при слиянии/перебазировании. Разница здесь заключается в том, что вы можете использовать git blame, чтобы увидеть различия между main и веткой бэкпорта, чтобы убедиться, что ничего не сломано.
  4. Опубликуйте новую ветку в свой репозиторий на Github:

    git push -u origin backport-3324
    
  5. Наконец, создайте запрос на объединение с помощью Github. Убедитесь, что вы отправляете запрос на объединение в ветку maintenance, а не в 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
    

Примечание

Обычно рекомендуется использовать флаг -n для git push , чтобы сначала проверить, что вы собираетесь отправить желаемые изменения в нужное место.

© 2005–2022 NumPy Developers
Licensed under the 3-clause BSD License.
https://numpy.org/doc/1.21/dev/development_workflow.html

Spec-Zone.ru

Настройки Оффлайн Что нового Помощь О нас
Spec-Zone .ru
спецификации, руководства, описания, API