Development workflow

您已经拥有自己的NumPy资源库的分叉副本,方法如下:Making your own copy (fork) of NumPy的副本(fork),Set up your fork您已经按照Git configuration配置了git,并且已按照Linking your repository to the upstream repo中所述链接上游存储库。

下面描述的是使用Git的推荐工作流程。

Basic workflow

简而言之:

  1. 为您所做的每组修改启动新的功能分支请参阅下面的below
  2. 黑客!请参阅下面的below
  3. 等结束了:
    • 贡献者:将您的功能分支推送到您自己的Github repo,并create a pull request
    • 核心开发者如果您想在不进一步审核的情况下推送更改,请参阅下面的below

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

也可以看看

有很多在线教程可以帮助你学习git有关特定git工作流程的讨论,请参阅有关linux git工作流程ipython git工作流程的讨论。

Making a new feature branch

首先,从upstream存储库获取新提交:

git fetch upstream

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

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

The editing workflow

Overview

# 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

In more detail

  1. 进行一些更改。当你觉得你做了一个完整的,工作的相关变化,继续下一步。

  2. 可选:使用git 状态(请参阅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 diffgit diff)将更改与上一个版本进行比较。这将打开一个简单的文本浏览器界面,突出显示您的文件和以前的verison之间的区别。

  4. 使用git 添加 modified_file添加任何相关的修改或新文件(参见git add )。这将文件放入暂存区,这是一个文件队列,将被添加到您的下一次提交。只添加具有相关,完整更改的文件。保留未完成更改的文件以供以后提交。

  5. 要将暂存文件提交到repo的本地副本,请执行git commit此时,文本编辑器将打开以允许您写入提交消息。请阅读commit message section以确保您正在写入格式正确且足够详细的提交消息。保存您的消息并关闭编辑器后,您的提交将被保存。对于小的提交,可以使用-m标志通过命令行传递短提交消息。For example, git commit -am "ENH: Some message".

    在某些情况下,你将看到这种形式的commit命令:git commit -a额外的-a标志会自动提交所有已修改的文件,并删除所有已删除的文件。这可以节省你一些类型的大量git 添加命令;然而,如果你不小心,它可以添加不必要的更改提交。有关详细信息,请参阅为什么使用-a标志 - 以及纠结工作副本问题中的有用用例说明。

  6. github上将更改推送到您的分叉repo:

    git push origin my-new-feature
    

    有关详细信息,请参阅git push

注意

假设你已经按照这些页面中的说明,git将创建一个默认链接到你的github repo调用originIn git >= 1.7 you can ensure that the link to origin is permanently set by using the --set-upstream option:

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

从现在起,git会知道my-new-feature与您自己的github中的my-new-feature 回购。随后的推送调用简化为以下:

git push

你必须对你创建的每个新分支使用--set-upstream

可能的情况是,当您处理您的编辑时,新的提交已添加到upstream,影响您的工作。在这种情况下,请按照本文档的Rebasing on master部分将这些更改应用到您的分支。

Writing the commit message

提交消息应该清楚,并遵循几个基本规则。例:

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: 固定 的另一个 一个去做;读者必须去其他地方寻找上下文。

开始提交消息的标准缩写是:

API: an (incompatible) API change
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

Asking for your changes to be merged with the main repo

当你觉得你的工作完成了,你可以创建一个拉请求(PR)。Github有一个很好的帮助页面,概述了提交请求的过程。

如果您的更改涉及API的修改或函数的添加/修改,您应该启动代码审查。这包括向NumPy邮件列表发送电子邮件,其中包含您的公关的链接,以及您的更改的描述和动机。

Rebasing on master

这会从上游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

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

git branch -D tmp

注意

在主控上重排碱基优先于上游合并回你的分支。不鼓励使用git 合并git pull 当在功能分支上工作时。

Recovering from mess-ups

有时,你搞乱合并。幸运的是,在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}

如果你实际上没有搞砸,但有合并冲突,你需要解决这些。这可能是一个棘手的事情,得到正确。有关如何执行此操作的详细说明,请参阅本文关于合并冲突

Additional things you might want to do

Rewriting commit history

注意

这只为你自己的功能分支。

在你做的承诺有一个令人尴尬的错字?或者也许你做了几个假的开始你会希望后代不去看。

这可以通过交互式基础结构来完成。

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

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 copule of structured_array_extensions.
...

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

  • 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

Deleting a branch on github

git checkout master
# delete branch locally
git branch -D my-unwanted-branch
# delete branch on github
git push origin :my-unwanted-branch

(注意test-branch之前的冒号:另请参阅:http://github.com/guides/remove-a-remote-branch

Several people sharing a single repository

如果你想与其他人一起工作,你们都在同一个仓库,甚至同一个分支,那么只是通过github分享。

第一个叉子NumPy到您的帐户,如从Making your own copy (fork) of NumPy

然后,转到您的forked存储库github页面,例如http://github.com/your-user-name/numpy

点击“管理”按钮,并将任何人添加到repo作为协作者:

../../_images/pull_button.png

现在所有的人都可以做:

git clone git@githhub.com:your-user-name/numpy.git

请记住,以git@开头的链接使用ssh协议并且是读写的;以git://开头的链接是只读的。

您的协作者可以直接提交到那个repo与通常:

git commit -am 'ENH - much better code'
git push origin my-feature-branch # pushes directly into your repo

Exploring your repository

要查看存储库分支和提交的图形表示形式:

gitk --all

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

git log

You can also look at the network graph visualizer for your github repo.

Backporting

Backporting是将在numpy / master中提交的新功能/修复复制回稳定版本分支的过程。要做到这一点你从一个分支你离开,樱桃选择你想从numpy/master,然后提交一个pull请求包含backport的分支。

  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. 你可能会碰到一些冲突樱桃在这里。这些解决方式与合并/ rebase冲突相同。除了这里你可以使用git blame来看看master和backported分支之间的区别,以确保没有什么被搞砸了。

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

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

Pushing changes to the main repo

这只有在您对主NumPy库提交权限时才有意义。

当您在功能分支中准备好一组“准备好”更改以准备NumPy的mastermaintenance分支时,您可以将它们推送到upstream如下:

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

    1. 只有少数,不相关的提交,然后喜欢rebasing:

      git fetch upstream
      git rebase upstream/master
      

      请参阅Rebasing on 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通常是个好主意,把你想要的变化推到你想要的地方。