为NumPy贡献 > 开发流程
您已经拥有自己的NumPy存储库的叉状副本,方法是制作 NumPy 的自己的副本(叉),设置叉子, 按照Git配置配置git并按照链接存储库中的说明链接上游存储库到上游回购。
下面介绍的是Git的推荐工作流程。
简而言之:
这种工作方式有助于保持工作井井有条,历史记录尽可能清晰。
也可以看看
有许多在线教程可以帮助您学习git。有关特定git工作流程的讨论,请参阅有关linux git工作流程和ipython git工作流程的这些讨论。
首先,从upstream
存储库中获取新的提交:
git fetch upstream
然后,基于上游存储库的master分支创建一个新分支:
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
进行一些更改。当您感觉到已经完成了一套完整的,有效的相关更改时,请继续执行下一步。
可选:检查哪些文件已更改(请参阅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)。这会将文件放入暂存区域,暂存区域是将添加到下一次提交的文件队列。仅添加具有相关完整更改的文件。保留未完成更改的文件以供以后提交。git add modified_file
要将暂存的文件提交到您的仓库的本地副本中,请执行。此时,将打开一个文本编辑器,使您可以编写提交消息。阅读提交消息部分,以确保您正在编写格式正确且足够详细的提交消息。保存消息并关闭编辑器后,将保存您的提交。对于琐碎的提交,可以使用该标志通过命令行传递简短的提交消息。例如,。git
commit
-m
git commit -am "ENH: Some message"
在某些情况下,您将看到以下形式的commit命令:。extra 标志自动提交所有修改的文件,并删除所有删除的文件。这样可以省去许多命令的输入。但是,如果您不小心,可能会在提交中添加不必要的更改。有关更多信息,请参见为什么使用-a标志?-以及复杂的工作副本问题中有用的用例描述。git commit
-a
-a
git
add
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-feature
与my-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.
描述更改的动机,错误修复的错误的性质或有关增强功能的一些详细信息也可以包含在提交消息中。消息应该易于理解,而无需查看代码更改。例如,提交消息就是不执行操作的示例。读者必须去别处寻找上下文。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
当您感觉工作完成时,可以创建拉取请求(PR)。Github有一个很好的帮助页面,概述了提交拉取请求的过程。
如果更改涉及对API的修改或对函数的添加/修改,则应
向NumPy邮件列表发送一封电子邮件,其中包含指向您的PR的链接以及更改的描述和动机。这可能会产生更改和反馈。如果您的更改可能会引起争议,那么从此步骤开始可能是谨慎的做法。
doc/release/upcoming_changes/
按照doc/release/upcoming_changes/README.rst
文件中的说明和格式将发行说明添加到目录中
。
这将通过上游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
如果您对上游也进行了更改的文件进行了更改,则可能会产生需要解决的合并冲突。在这种情况下,请参见 下面的帮助。
最后,在成功重新建立基础后,删除备份分支:
git branch -D tmp
注意
与基于上游合并回到分支机构相比,基于master优先。不建议在功能分支上使用和。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 copule of structured_array_extensions.
...
并且6ad92e5
是master
分支中的最后一次提交。假设我们要进行以下更改:
将提交消息重写为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
如果出现错误,则如上所述可以再次进行恢复。
git checkout master
# delete branch locally
git branch -D my-unwanted-branch
# delete branch on github
git push origin :my-unwanted-branch
(请注意:
之前的冒号test-branch
。另请参见:https :
//github.com/guides/remove-a-remote-branch
如果您想与其他人一起从事某些工作,而您都将它们提交到同一存储库,甚至是同一分支中,那么只需通过github共享即可。
首先,从制作您自己的NumPy副本(分叉)开始,将NumPy拨入您的帐户。
然后,转到您的分叉存储库github页面,说
https://github.com/your-user-name/numpy
单击“管理”按钮,然后以协作者的身份将其他任何人添加到存储库中:
现在所有这些人都可以做:
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
反向移植是将numpy / master中提交的新功能/修复复制
回稳定版本分支的过程。为此,请在要反向移植到的分支上创建一个分支,从中选择所需的提交
numpy/master
,然后为包含反向移植的分支提交拉取请求。
首先,您需要创建将要处理的分支。这需要基于较旧版本的NumPy(而非主版本):
# 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
现在,您需要使用git cherry-pick将 master的更改应用于此分支 :
# 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
您可能会在这里遇到一些冲突。这些问题的解决方法与合并/重新设置冲突相同。除了这里,您可以使用git blame来查看master和backported分支之间的区别,以确保没有发生任何事情。
将新分支推送到您的Github存储库:
git push -u origin backport-3324
最后使用Github发出拉取请求。确保它是针对维护分支而不是master,Github通常会建议您针对master提出拉取请求。
仅当您具有对主要NumPy存储库的提交权限时,这才有意义。
当功能分支中有一组准备就绪的更改可用于NumPy master
或maintenance
分支时,可以将其推upstream
如下:
首先,合并或基于目标分支。
然后只有少数不相关的提交更喜欢重新定级:
git fetch upstream
git rebase upstream/master
请参阅在master上重定基础。
如果所有提交都相关,请创建一个合并提交:
git fetch upstream
git merge --no-ff upstream/master
检查您要推送的内容是否合理:
git log -p upstream/master..
git log --oneline --graph
推送到上游:
git push upstream my-feature-branch:master
注意
通常最好使用该-n
标志来首先检查您是否要将所需的更改推送到所需的位置。git push