开发工作流

您已经有了自己的 NumPy 存储库,通过以下方式 创建NumPy fork制作本地副本 ,您已配置 git 通过以下 Git配置 ,并已链接上游存储库,如中所述 Linking your repository to the upstream repo .

下面描述的是一个推荐的Git工作流。

基本工作流程

简而言之:

  1. 开始新的 特征分支 对于您所做的每一组编辑。见 below .

  2. 砍掉!见 below

  3. 完成后:

    • 贡献者 :将您的功能分支推到您自己的Github回购,以及 create a pull request .

    • 核心开发者 :如果要在不进行进一步检查的情况下推动更改,请参阅注释 below .

这种工作方式有助于保持工作的良好组织和历史尽可能清楚。

参见

有很多在线教程可以帮助您 learn git . 有关特定Git工作流的讨论,请参见 linux git workflowipython git workflow .

创建新功能分支

首先,从 upstream 储存库:

git fetch upstream

然后,基于上游存储库的主分支创建一个新分支:

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 . 此时,将打开一个文本编辑器,允许您编写提交消息。阅读 commit message section 以确保您正在编写一个格式正确且足够详细的提交消息。保存消息并关闭编辑器后,将保存提交。对于普通提交,可以使用 -m 旗帜。例如, git commit -am "ENH: Some message" .

    在某些情况下,您将看到commit命令的这种形式: 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将创建一个默认链接,指向 github 回购称为回购 origin . 在git>=1.7中,可以使用 --set-upstream 选项:

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

从今以后 git 会知道 my-new-featuremy-new-feature 你自己的分支 github 回购协议。随后的推送调用将简化为以下内容:

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.

描述变更的动机、bug修复的性质或关于增强功能的一些细节,也可以将其包含在提交消息中。消息应该是可以理解的,而不需要考虑代码的变化。像这样的提交消息 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有一个很好的帮助页面,概述了 filing pull requests .

如果您的更改涉及对API的修改或对函数的添加/修改,请在 doc/release/upcoming_changes/ 目录中的说明和格式 doc/release/upcoming_changes/README.rst 文件。

审查你的公关

我们会尽快审查pull请求,通常是在一周内。如果您在两周内没有收到任何评论,可以通过在您的PR上添加评论(这将通知维护人员)来请求反馈。

如果你的公关是大型或复杂的,要求输入的numpy讨论邮件列表也可能是有用的。

在主服务器上重新平衡

这将使用上游的更改更新您的功能分支 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 master branch
git rebase upstream/master

如果对同样在上游更改的文件进行了更改,则可能会生成需要解决的合并冲突。见 below 在这种情况下寻求帮助。

最后,在成功的重新设置后删除备份分支:

git branch -D tmp

注解

在master上重新定位比在上游合并回分支更可取。使用 git mergegit 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}

如果你没有把事情搞砸,但是有合并冲突,你需要解决这些冲突。这可能是更棘手的事情之一。有关如何执行此操作的详细说明,请参见 this article on merging conflicts .

你可能想做的其他事情

重写提交历史记录

注解

只为您自己的功能分支执行此操作。

你做出的承诺中有一个令人尴尬的拼写错误?或者,也许你做了一些错误的开始,你希望后人不要看到。

这可以通过 交互式再平衡 .

假设提交历史记录如下所示:

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 为了更明智的事情。

  • 结合承诺 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

如果它出了问题,恢复是可能的,正如解释的那样。 above .

删除上的分支 github

git checkout master
# 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 fork .

然后,转到您的复刻存储库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

探索您的存储库

要查看存储库分支和提交的图形表示,请执行以下操作:

gitk --all

要查看此分支的线性提交列表,请执行以下操作:

git log

你也可以看看 network graph visualizer 为了你 github 回购协议。

反向移植

backporting是复制在中提交的新功能/修复程序的过程。 numpy/master 回到稳定释放分支。要做到这一点,你需要从你要反向移植的分支上创建一个分支,Cherry选择你想要的提交。 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. 现在,您需要使用 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. 你可能会在这里遇到一些冲突。这些问题的解决方法与合并/重新平衡冲突相同。除了这里你可以用 git blame 查看主分支和后端口分支之间的区别,以确保没有任何事情出错。

  4. 将新分支推送到Github存储库:

    git push -u origin backport-3324
    
  5. 最后使用Github发出请求。确保它是针对维护分支而不是主服务器的,Github通常会建议您对主服务器提出请求。

将更改推送到主回购

需要对主NumPy回购的提交权限。

当您在一个功能分支中有一组“准备就绪”的更改准备好进行numpy时 mastermaintenance 树枝,你可以把它们推到 upstream 如下:

  1. 首先,在目标分支上合并或重新设置基。

    1. 只有少数不相关的提交才喜欢重新平衡:

      git fetch upstream
      git rebase upstream/master
      

      在主服务器上重新平衡 .

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

      git fetch upstream
      git merge --no-ff upstream/master
      
  2. 检查你要推的东西看起来是否合理:

    git log -p upstream/master..
    git log --oneline --graph
    
  3. 向上游推:

    git push upstream my-feature-branch:master
    

注解

通常使用 -n 旗到 git push 首先检查是否要将所需更改推送到所需的位置。