Рабочий процесс разработки
У вас уже есть своя вилка репозитория NumPy, созданная, следуя инструкциям Создание вилки NumPy, Создание локальной копии. Вы настроите git, следуя инструкциям Настройка Git, и связали репозиторий с родительским репозиторием, как описано в Связывание вашего репозитория с родительским репозиторием.
Ниже описан рекомендуемый рабочий процесс с Git.
Основной рабочий процесс
Кратко:
- Для каждого набора изменений начинайте новую ветвь функции. См. ниже.
- Приступайте к работе! См. ниже
-
По завершении:
- Авторы: отправьте вашу ветвь функции в свой репозиторий на 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
Подробности
- Внесите изменения. Когда вы чувствуете, что внесли полный и рабочий набор связанных изменений, переходите к следующим шагам.
-
Необязательно: Проверьте, какие файлы были изменены с помощью
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")
- Необязательно: Сравните изменения с предыдущей версией, используя
git diff(git diff). Это откроет простой текстовый интерфейс браузера, который выделит разницу между вашими файлами и предыдущей версией. - Добавьте все соответствующие измененные или новые файлы, используя
git add modified_file(см. git add). Это помещает файлы в область подготовки — очередь файлов, которые будут добавлены к вашему следующему коммиту. Добавляйте только файлы с связанными, завершенными изменениями. Оставляйте файлы с незавершенными изменениями для последующих коммитов. -
Чтобы зафиксировать подготовленные файлы в локальной копии репозитория, выполните
git commit. На этом этапе откроется текстовый редактор, чтобы вы могли написать сообщение коммита. Прочитайте раздел сообщение коммита, чтобы убедиться, что вы пишете сообщение коммита в правильном формате и с достаточной степенью детализации. После сохранения вашего сообщения и закрытия редактора ваш коммит будет сохранен. Для тривиальных коммитов короткое сообщение коммита можно передать через командную строку с использованием флага-m. Например,git commit -am "ENH: Some message".В некоторых случаях вы увидите эту форму команды коммита:
git commit -a. Дополнительный флаг-aавтоматически коммитит все измененные файлы и удаляет все удаленные файлы. Это может сэкономить вам время на написание множества командgit add; однако, если вы не внимательны, это может добавить нежелательные изменения в коммит. Для получения дополнительной информации см. почему флаг -a? — и описание полезного случая использования в проблеме запутанной рабочей копии. -
Отправьте изменения в свой вилку репозитория на 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» и добавьте других людей в репозиторий в качестве коллабораторов:
Теперь все эти люди могут:
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, а затем отправляете запрос на объединение для ветки с бэкпортом.
-
Сначала вам нужно создать ветку, в которой вы будете работать. Она должна быть основана на более старой версии 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
-
Теперь вам нужно применить изменения из 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
- При бэкпортировании могут возникнуть конфликты. Они разрешаются так же, как конфликты при слиянии/перебазировании. Разница здесь заключается в том, что вы можете использовать git blame, чтобы увидеть различия между main и веткой бэкпорта, чтобы убедиться, что ничего не сломано.
-
Опубликуйте новую ветку в свой репозиторий на Github:
git push -u origin backport-3324
- Наконец, создайте запрос на объединение с помощью Github. Убедитесь, что вы отправляете запрос на объединение в ветку maintenance, а не в main; Github, как правило, предложит вам создать запрос на объединение с main.
Отправка изменений в основной репозиторий
Требуются права на коммиты в основной репозиторий NumPy.
Когда у вас есть набор готовых изменений в ветке функции, готовых для ветвей main или maintenance NumPy, вы можете отправить их в upstream следующим образом:
-
Сначала объедините или перебазируйте на целевую ветку.
-
Если несколько, не связанных друг с другом коммитов, предпочитайте перебазирование:
git fetch upstream git rebase upstream/main
-
Если все коммиты взаимосвязаны, создайте коммит слияния:
git fetch upstream git merge --no-ff upstream/main
-
-
Проверьте, что то, что вы собираетесь отправить, выглядит осмысленно:
git log -p upstream/main.. git log --oneline --graph
-
Опубликуйте в 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