第一节.Numpy开发者指南

一.为Numpy项目贡献源码

1.使用Numpy源码

1.1.概览

这一小部分内容主要描述numpy项目的Git和GitHub工作流程形式。对于使用不同方式操作numpy这里相对应有几种不同的工作流程形式。这不是一个全面的git参考，它只是我们自己项目的一个工作流程。它是为github托管服务量身定做的。你可能会发现更好或更快的方式来完成与Git的东西，但这些应该让你开始。关于Git的知识这里不做过多的介绍，请您参照Git文档学习。

1.2安装Git

	安装命令	下载地址
Debian / Ubuntu	sudo apt-get install git-core
Fedora	sudo yum install git-core
windows	下载安装git客户端	http://code.google.com/p/msysgit/downloads/list
OS	使用git-osx-installer	http://code.google.com/p/git-osx-installer/downloads/list

如果想要了解Git的更多东西，请参照Git页面：https://git-scm.com/

看看github帮助页面提供的github安装：https://help.github.com/

1.3.关注最新资源

如果你只是想要follow最新的NumPy源代码，这些是说明，但你现在不需要做任何的开发。如果您想提供补丁（优秀！）或进行更广泛的NumPy开发，请参阅开发工作流程。

步骤是：

安装Git
把代码从Git仓库拉倒本地
时时更新本地

1.3.1将远程代码复制到本地

克隆命令：

git clone git://github.com/numpy/numpy.git

你现在有一个新的numpy目录中的代码树的副本。如果这不起作用，您可以尝试替代只读网址：

git clone https://github.com/numpy/numpy.git

1.3.2.更新代码

您可能想要时时拉下最新的代码。按照下面方法做就行：

cd numpy
git fetch
git merge --ff-only

numpy中的树现在将具有来自初始存储库的最新更改。

1.4.Git开发者模式

1.4.1.使用Git开发者模式开始项目

这一部分将详细介绍如何设置git来处理NumPy源代码。如果您已经安装了git，请跳到“开发”工作流程。

1.4.2.基本配置

安装git
在Git命令行中执行下面命令

git config --global user.email [email protected]
git config --global user.name "Your Name Comes Here"

1.4.3.制作你自己的NumPy（fork）

你只需要做一次。这里的说明与http://help.github.com/forking/上的说明非常相似 - 请参阅该页面以获取更多详细信息。我们在这里重复一些，只是为了说明NumPy项目的细节，并建议一些默认名称。

1.4.4.设置和配置一个github帐户

如果您没有github帐户，请转到github页面，然后创建一个。

然后，您需要配置您的帐户以允许写入权限 - 请参阅在github帮助上生成SSH密钥帮助。

1.4.5.创建您自己的NumPy分叉

登录到你的github帐户。
在NumPy github上转到NumPy github主页。
点击fork按钮
一会儿之后，你应该在自己的NumPy副本的主页上找到自己的位置。

1.4.6.设置你的分支

首先，按照制作您自己的NumPy副本（分支）的说明进行操作。

 git clone https://github.com/your-user-name/numpy.git
 cd numpy
 git remote add upstrem git：//github.com/numpy/numpy.git

1.4.7.克隆你的分支

1.克隆你的分支到本地计算机

 git clone [https://github.com/your-user-name/numpy.git](https://github.com/your-user-name/numpy.git)

2.检查，改变目录到你的新repo：cd numpy。然后git branch -a展示你所有分支。你会得到像这样的东西：*

 * master
 remotes/origin/master

这告诉你，你目前处在主分支上，并且你也有一个远程连接到origin / master。什么远程存储库是远程/来源？尝试使用git remote -v来查看远程的URL。这样他们会指向你的github fork。

现在，您要连接到上游的NumPy github存储库，因此您可以合并来自trunk的更改。

将您的存储库链接到上游repo

 cd numpy
 git remote upstream git：//github.com/numpy/numpy.git

这里的上游只是我们用来引用NumPy github上的主要NumPy存储库的任意名称。请注意，我们使用了git：//而不是https：//. git：// URL是只读的。这意味着我们不能意外（或故意）写入上游的repo，我们只会用它来合并到我们自己的代码中。

只是为了您自己的满意，展示自己现在有了一个新的“远程”，使用git remote -v show，给你类似于：

upstream     git://github.com/numpy/numpy.git (fetch)
upstream     git://github.com/numpy/numpy.git (push)origin       
https://github.com/your-user-name/numpy.git (fetch)
origin       https://github.com/your-user-name/numpy.git (push)

要与NumPy中的更改保持同步，您需要设置您的存储库，以便默认情况下从上游进行提取。这可以通过以下方式完成：

git config branch.master.remote upstream
git config branch.master.merge refs/heads/master

您也可能想要轻松访问发送到NumPy存储库的所有请求：

 git config --add remote.upstream.fetch'+ refs / pull // head：refs / remotes / upstream / pr /'

现在你的配置文件应该看起来像（从$ cat .git / config）：

[core]
        repositoryformatversion = 0
        filemode = true
        bare = false
        logallrefupdates = true
        ignorecase = true
        precomposeunicode = false
[remote "origin"]
        url = https://github.com/your-user-name/numpy.git
        fetch = +refs/heads/*:refs/remotes/origin/*
[remote "upstream"]
        url = git://github.com/numpy/numpy.git
        fetch = +refs/heads/*:refs/remotes/upstream/*
        fetch = +refs/pull/*/head:refs/remotes/upstream/pr/*
[branch "master"]
        remote = upstream
        merge = refs/heads/master

1.5.Git配置

个人的Git配置存储在.gitconfig文件中，这儿是一个示例.gitconfig文件

[user]
        name = Your Name
        email = [email protected]

[alias]
        ci = commit -a
        co = checkout
        st = status -a
        stat = status -a
        br = branch
        wdiff = diff --color-words

[core]
        editor = vim

[merge]
        summary = true

你可以使用编辑上面这个文件或者使用git config --global命令行配置

git config --global user.name "Your Name"
git config --global user.email [email protected]
git config --global alias.ci "commit -a"
git config --global alias.co checkout
git config --global alias.st "status -a"
git config --global alias.stat "status -a"
git config --global alias.br branch
git config --global alias.wdiff "diff --color-words"
git config --global core.editor vim
git config --global merge.summary true

为了配置另一台电脑，你可以拷贝你的.gitconfig文件,或者执行上面的命令

1.5.1.user.name和user.email

下面这是告诉git你是谁的最好的方式，用于标记您对代码所做的任何更改。最简单的方法是从命令行：

git config --global user.name "Your Name"
git config --global user.email [email protected]

这将会将设置写到你的包含用户和邮件配置得git配置文件，

[user]
      name = Your Name
      email = [email protected]

你可能会从一些别名中受益于常见的命令。

git config --global alias.ci "commit -a"
git config --global alias.co checkout
git config --global alias.st "status -a"
git config --global alias.stat "status -a"
git config --global alias.br branch
git config --global alias.wdiff "diff --color-words"

在配置文件表现如下：

[alias]
        ci = commit -a
        co = checkout
        st = status -a
        stat = status -a
        br = branch
        wdiff = diff --color-words

1.5.2.编辑器

您可能还想确保使用您选择的编辑器

git config --global core.editor vim

1.5.3.合并

在合并时执行汇总(~/.gitconfigfile again):

[merge]
   log = true

或者使用命令行:

git config --global merge.log true

1.6.开发工作流程

你已经拥有了你自己的NumPy仓库，你可以按照下面的方式创建你自己的NumPy（分支），设置你的分支，按照Git的配置配置git，链接了上游仓库，链接你的仓库到上游repo。

下面介绍的是Git推荐的工作流程。

1.6.1.基本工作流程

简而言之

为您所做的每一编辑集启动一个新的功能分支。
劈开
当结束时
- 贡献者：把你最新的分支推动到你自己的Github仓库，并创建一个请求。
- 核心开发人员：如果您想推进更改而无需进一步审核，请参阅：https://docs.scipy.org/doc/numpy-dev/dev/gitwash/development_workflow.html#pushing-to-main。

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

1.6.2.创建一个新的分支

首先，从上游存储库中提取新的提交:

git fetch upstream

然后，根据上游存储库的主分支创建一个新分支：

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

1.6.3.编辑工作流

1.6.3.1.概述

# 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.6.3.2.详细说明

做一些改变。如果您觉得自己已经完成了一套完整的相关更改，请继续下一步。

可选：使用git status（查看git状态）检查哪些文件已更改。你会看到一个这样的列表：:

# 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添加任何相关的修改或新文件。这将文件放入暂存区域，这里是一个文件队列，被添加到您暂存区的文件下一步将被提交。只添加具有相关的完整更改的文件。留下未完成更改的文件以供稍后提交。

5.执行git commit命令将提交的文件提交到你的本地仓库。

 git commit -m "提交信息"

6.将更改推送到你自己的Git仓库：

git push origin my-new-feature

想要了解更多的信息，请看git push部分

注意

假设你已经按照这些页面的指示，git会创建一个默认的链接到你的github仓库，这个链接被称为origin。在git> = 1.7中，通过使用 - set-upstream option可以确保永久性地的链接到origin：

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

从此以后，Git会知道my-new-feature与你自己的github仓库中的新特征分支有关。随后的推送简化为以下内容即可:

git push

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

1.6.4.写确认信息

提交消息应该清楚，并遵循一些基本规则。例:

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是一个不能作为提交信息的; 读者必须去其他地方寻找背景。

Standard acronyms to start the commit message with are:

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

1.6.5.您的更改与主要的仓库合并

当你感觉你的工作已经完成时，你可以创建一个拉取请求（PR）。 Github有一个很好的帮助页面，概述了提取请求的过程。

如果您的更改涉及API的修改或功能的添加/修改，则应启动代码审查。这涉及到发送电子邮件到NumPy邮件列表，与一个链接到您的和一个描述和您的更改信息文件.

1.6.6.在master上Rebasing

上游 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

1.6.7.从mess-ups恢复

有时候，你搞垮了合并或重组。幸运的是，在Git中，从这样的错误中恢复是相对简单的。

如果你在重建期间搞砸了:

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}

如果你实际上并没有搞砸，但是有合并冲突，你需要解决这些冲突。这可能是要纠正的棘手的事情之一。

1.6.8.你可能想要做的其他事情

1.6.8.1.重写提交历史

注意

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

你犯了一个尴尬的错字？也许你做了几个错误的开始，你希望后代不要看到。

这可以通过交互重组来实现。

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

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

and6ad92e5是最新提交的主要分支. 假想我们想要做下面这些改动:

重写提交信息为 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

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

如果出错了，恢复是可能的，如上所述。

1.6.9.在GitHub上删除一个分支

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

(关于删除分支的更多信息请看:http://github.com/guides/remove-a-remote-branch

1.6.10.几个人共享一个仓库

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

首先将NumPy分叉到您的帐户中，如从制作NumPy的分支。

然后，去你的分叉库github页面http：//github.com/your-user-name/numpy

点击“管理员”按钮，并添加其他人作为合作者：

$../../\_images/pull\_button.png$

现在，所有这些人都可以这样做:

git clone [email protected]: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

1.6.11.探索你的存储库

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

gitk
--
all

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

git log

你也可以看看你的github仓库的网络图可视化器。

1.6.12.向后移植

Backporting是将提交的numpy / master 后移植的新功能/修复复制到稳定版本分支的过程。要做到这一点，你从你正在反向移植的分支上创建一个分支，选择你想从numpy / master提交，然后向包含backport的分支提交一个pull请求。

首先，你需要建立你将要工作的分支。这需要基于旧版本的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

现在您需要使用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

你可能会遇到一些cherry picking冲突。这些解决方式与合并/重组冲突相同。除了这里，你可以使用blameto看到主和backported分支之间的区别，以确保没有任何事情被搞砸了.
推新的分支到你的Github仓库:
```
git push -u origin backport-3324
```
最后使用Github进行请求。确保它是维护分支而不是主控，Github通常会建议你对主控进行拉动请求。.

1.6.13.促进对主要仓库的更改

这只有在你拥有NumPy主要仓库的权限时才有意义

当你准备好NumPy的master或maintenance分支时，你可以将一系列“准备好”的变化推给他们：

首先，在目标分支上合并或重新绑定h.
1. 只有少数，不涉及提交，偏向于rebasing：
```
git fetch upstream
git rebase upstream/master
```
2. 如果所有提交都相关，则创建一个合并提交：
```
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先检查你是否要将所需的更改推送到所需的位置。

第一节.Numpy开发者指南