开发流程#

您已经拥有 NumPy 仓库的个人 fork 拷贝,已配置 Git,并已按照将您的仓库链接到上游仓库中说明的步骤链接了上游仓库。以下是推荐的 Git 工作流程。

基本流程#

简而言之

  1. 为每组编辑创建一个新的功能分支。参见下文

  2. 开始编码!参见下文

  3. 完成后

    • 贡献者:将您的功能分支推送到您自己的 GitHub 仓库,并创建一个拉取请求

    • 核心开发者:如果您想在无需进一步审查的情况下推送更改,请参阅下文中的说明。

这种工作方式有助于使工作井然有序,并使历史记录尽可能清晰。

创建新的功能分支#

首先,从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检查哪些文件已更改。您将看到如下所示的列表

    # 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与上一个版本比较更改。这将打开一个简单的文本浏览器界面,突出显示您的文件与上一个版本之间的差异。

  4. 使用git add modified_file添加任何相关的修改或新文件。这将文件放入暂存区,这是一个将添加到下一个提交的文件队列。只添加具有相关、完整更改的文件。将包含未完成更改的文件留待以后提交。

  5. 要将暂存的文件提交到本地仓库副本中,请执行git commit。此时,将打开一个文本编辑器,允许您编写提交消息。阅读提交消息部分,确保您编写了格式正确且足够详细的提交消息。保存消息并关闭编辑器后,您的提交将被保存。对于琐碎的提交,可以通过命令行使用-m标志传递简短的提交消息。例如,git commit -am "ENH: Some message"

    在某些情况下,您会看到这种形式的提交命令:git commit -a。额外的-a标志会自动提交所有修改的文件并删除所有已删除的文件。这可以节省您输入大量git add命令的时间;但是,如果您不小心,它可能会将不需要的更改添加到提交中。

  6. 将更改推送到您在 GitHub 上的分支。

    git push origin my-new-feature
    

注意

假设您已按照这些页面中的说明进行操作,git 将创建一个到您的 GitHub 仓库的默认链接,名为origin。您可以使用--set-upstream选项确保永久设置与 origin 的链接

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

从现在开始,git将知道my-new-feature与您自己的 GitHub 仓库中的my-new-feature分支相关。随后的推送调用将简化为以下内容

git push

您必须为创建的每个新分支使用--set-upstream

在您处理编辑的同时,可能会向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
CI: continuous integration
DEP: deprecate something, or remove a deprecated object
DEV: development tool or utility
DOC: documentation
ENH: enhancement
MAINT: maintenance commit (refactoring, typos, etc.)
MNT: alias for MAINT
NEP: NumPy enhancement proposals
REL: related to releasing numpy
REV: revert an earlier commit
STY: style fix (whitespace, PEP8)
TST: addition or modification of tests
TYP: static typing
WIP: work in progress, do not merge
跳过持续集成命令#

默认情况下,每个 PR 都会运行许多持续集成 (CI) 作业,从在不同的操作系统和硬件平台上运行测试套件到构建文档。在某些情况下,您可能已经知道不需要 CI(或不需要全部 CI),例如,如果您处理 CI 配置文件、README 中的文本或不参与常规构建、测试或文档序列的其他文件。在这种情况下,您可以通过在 PR 的每个提交消息中包含一个或多个这些片段来显式跳过 CI

  • [skip ci]:跳过所有 CI

    仅当您尚未准备好对您的 PR 运行检查时才推荐(例如,如果这只是一个草稿)。

  • [skip actions]:跳过 GitHub Actions 作业

    GitHub Actions 是运行大部分 CI 检查的地方,包括 linter、基准测试、为大多数架构和操作系统运行基本测试以及多种编译器和 CPU 优化设置。查看这些检查的配置文件。

  • [skip azp]:跳过 Azure 作业

    Azure 是运行所有全面测试的地方。这是一个昂贵的运行,如果您只进行文档更改,则通常可以跳过它。查看这些检查的主要配置文件。

  • [skip circle]:跳过 CircleCI 作业

    CircleCI 用于构建文档并在每个 PR 中存储生成的工件以进行预览。此检查还将运行所有文档字符串示例并验证其结果。例如,如果您没有进行文档更改,而是更改了函数的 API,则可能需要运行这些测试以验证文档测试是否仍然有效。查看这些检查的配置文件。

  • [skip cirrus]:跳过 Cirrus 作业

    CirrusCI 主要触发 Linux aarch64 和 MacOS Arm64 轮子上传。查看这些检查的配置文件。

测试构建轮子#

NumPy 目前使用cibuildwheel 通过持续集成服务构建轮子。为了节省资源,cibuildwheel 轮子构建器不会默认在每个 PR 或对主分支的每次提交上运行。

如果您想测试您的拉取请求不会破坏轮子构建器,您可以通过将[wheel build]附加到 PR 中最新提交的提交消息的第一行来做到这一点。请仅对与构建相关的 PR 执行此操作,因为运行所有轮子构建速度缓慢且成本高昂。

通过 GitHub Actions 构建的轮子(包括 64 位 Linux、x86-64 macOS 和 32/64 位 Windows)将作为 zip 文件中的工件上传。您可以从“轮子构建器”操作的“摘要”页面访问它们。通过 Cirrus CI 构建的 aarch64 Linux 和 arm64 macOS 轮子不可作为工件使用。此外,轮子将在以下条件下上传到https://anaconda.org/scientific-python-nightly-wheels/

  • 通过每周的 cron 作业或

  • 如果已手动触发 GitHub Actions 或 Cirrus 构建,这需要相应的权限

如果构建是由以v开头的仓库标签触发的,则车轮将上传到https://anaconda.org/multibuild-wheels-staging/

征求邮件列表的意见#

如果您计划添加新功能或更改API,最好先向NumPy 邮件列表 发送电子邮件,征求意见。如果您在一周内没有收到回复,可以再次 ping 该列表。

请求将您的更改合并到主仓库#

当您认为工作完成时,您可以创建一个拉取请求 (PR)。如果您的更改涉及对API的修改或函数的添加/修改,请按照doc/release/upcoming_changes/README.rst 文件中的说明和格式,在doc/release/upcoming_changes/ 目录中添加发行说明。

获取您的PR审核#

我们会尽快审核拉取请求,通常在一周内完成。如果您在两周内没有收到任何审核评论,请随时在您的PR上添加评论以索取反馈(这会通知维护者)。

如果您的PR很大或很复杂,也可以在numpy-discussion邮件列表中寻求意见。

基于main分支进行rebase#

这会用来自上游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

如果您对上游也更改过的文件进行了更改,这可能会产生需要您解决的合并冲突。在这种情况下,请参阅下文以获取帮助。

最后,在成功rebase后删除备份分支。

git branch -D tmp

注意

基于main分支进行rebase优于将上游合并回您的分支。在处理功能分支时,不建议使用git mergegit pull

从错误中恢复#

有时,您会弄乱合并或rebase。幸运的是,在Git中,从这些错误中恢复相对简单。

如果您在rebase过程中出错

git rebase --abort

如果您在rebase后发现自己弄错了

# 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}

如果您实际上没有弄错,但存在合并冲突,则需要解决这些冲突。

您可能还想做的事情#

重写提交历史#

注意

仅对您自己的功能分支执行此操作。

您提交中是否有令人尴尬的错别字?或者您可能进行了多次错误尝试,希望后代看不到。

这可以通过*交互式rebase*来完成。

假设提交历史如下所示

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

并且6ad92e5main分支中的最后一个提交。假设我们要进行以下更改

  • 13d7934的提交消息重写为更合理的內容。

  • 将提交2dec1aca815645eadc391合并为一个。

我们按如下步骤操作

# 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

单击“管理”按钮,并将任何其他人添加到仓库作为协作者。

../_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

检出现有拉取请求中的更改#

如果您想测试拉取请求中的更改或在新拉取请求中继续工作,则需要将提交克隆到您分叉仓库中的本地分支。

首先,确保您的上游指向主仓库,如将您的仓库链接到上游仓库所示。

然后,获取更改并创建一个本地分支。假设$ID是拉取请求编号,$BRANCHNAME是您要创建的*新本地*分支的名称

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

检出新创建的分支。

git checkout $BRANCHNAME

您现在拥有拉取请求中的更改。

浏览您的仓库#

要查看仓库分支和提交的图形表示

gitk --all

要查看此分支的提交线性列表

git log

反向移植#

反向移植是将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. 现在,您需要使用git cherry-pick将来自main的更改应用于此分支。

    # 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. 您可能会在此处挑选樱桃时遇到一些冲突。这些冲突的解决方法与合并/rebase冲突相同。除了在这里您可以使用git blame来查看main和反向移植分支之间的区别,以确保没有任何东西被搞乱。

  4. 将新分支推送到您的GitHub仓库。

    git push -u origin backport-3324
    
  5. 最后,使用GitHub创建拉取请求。确保它是针对维护分支而不是main分支的,GitHub通常会建议您针对main分支创建拉取请求。

将更改推送到主仓库#

需要对NumPy主仓库的提交权限。

当您在功能分支中有一组准备好的更改,准备用于NumPy的mainmaintenance分支时,您可以将其推送到upstream,如下所示:

  1. 首先,合并或rebase到目标分支。

    1. 只有少数不相关的提交才更喜欢rebase。

      git fetch upstream
      git rebase upstream/main
      

      参见基于main分支进行rebase

    2. 如果所有提交都相关,则创建合并提交。

      git fetch upstream
      git merge --no-ff upstream/main
      
  2. 检查您即将推送的内容是否合理。

    git log -p upstream/main..
    git log --oneline --graph
    
  3. 推送到上游。

    git push upstream my-feature-branch:main
    

注意

通常最好对git push使用-n标志,以首先检查您是否要将所需的更改推送到所需的位置。