开发工作流

Note: consider watching SciPy Development Workflow before or after reading to see an example of fixing a bug and submitting a pull request.

在……里面 开发环境快速入门指南(MacOS) 或 开发环境快速入门指南(Ubuntu) 中，您创建了您自己的SciPy存储库的分支(副本)，在您自己的机器上克隆了存储库，并从该源代码构建了SciPy。在开始这里之前，在您开始修改本网站之前，您还需要做另外两件事，只需做一次。

1. 在终端中，向Git介绍自己：：

   git config --global user.email you@yourdomain.com
   git config --global user.name "Your Name"
   

   这些信息归功于您的工作，但是请注意，如果您将您的工作“推”到GitHub上，这些信息将会公开可用。看见 Setting your commit email address in Git 了解更多信息。

2. 导航到本地SciPy存储库的根目录，然后输入：

   git remote add upstream https://github.com/scipy/scipy.git
   

   这会将名称与 upstream 官方的SciPy存储库位于 https://github.com/scipy/scipy.git 。请注意，当您克隆SciPy存储库的分支时，Git已经关联了该名称 origin 用你的叉子。您需要这两个选项的原因是 "remotes" 您通常会从官方资源库中的最新版本的SciPy开始 upstream ，进行更改，将您的更改“推送”到存储库的分支 origin ，然后提交一个“拉请求”，要求本网站将您的更改从您的分支“拉”到官方存储库。

3. 初始化git子模块：：

   git submodule update --init
   

   这将获取并更新SciPy需要的所有子模块(例如 Boost )。

基本工作流程

简而言之：

1. 开始一个新的 功能分支 对于您所做的每一组编辑。看见 below 。

2. 砍掉吧！看见 below 。

3. 完成后：

   • 贡献者 ：将您的功能分支推送到您自己的Github回购，然后 create a pull request 。

   • 核心开发者 如果要在不进行进一步审查的情况下推送更改，请参阅说明 below 。

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

参见

有许多在线教程可以帮助您 learn git 。有关特定git工作流的讨论，请参阅 linux git workflow ，以及 ipython git workflow 。

创建新的要素分支

首先，导航到终端中的SciPy根目录，并从 upstream 存储库：：

git fetch upstream

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

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

同样，您可能希望使您自己的存储库的主分支保持最新，并基于此创建一个新分支：：

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

按照顺序，这些命令

1. 确保 master 您本地存储库的分支已签出，

2. 应用来自的所有最新更改 upstream/master (本网站的主存储库主分支)发送到您当地 master 分支，以及

3. 创建并签出新分支 (-b )根据您当地的情况 master 布兰奇。

在任何情况下，重要的是您的功能分支包含来自上游主版本的最新更改，以帮助避免 merge conflicts 当需要提交拉取请求时。

在继续之前构建此分支并运行测试也是一个好主意。假设你跟踪了 开发环境快速入门指南(MacOS) 或 开发环境快速入门指南(Ubuntu) 要设置您的开发环境，您需要激活您的开发虚拟环境，执行就地构建，并运行测试：

conda activate name-of-your-virtual-environment
python setup.py build_ext --inplace
python runtests.py -v

否则，请参见 从源头开始构建 ， 在本地运行SciPy测试 了解更多信息。

编辑工作流

概述

# 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. Optional: Compare the changes with the previous version using with git diff (git diff). This brings up a simple text browser interface that highlights the difference between your files and the previous version.

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-feature 与 my-new-feature 您自己的分支机构 github 回购。随后的推送呼叫将简化为以下内容：

git push

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

情况可能是，在您进行编辑时，已将新的提交添加到 upstream 会影响你的工作。在这种情况下，请遵循 重新基于主数据库 将这些更改应用到您的分支机构的说明。

正在写入提交消息

提交消息应该清晰，并遵循一些基本规则。示例：：

ENH: add functionality X to SciPy.<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 SciPy
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 SciPy

注解

您可以添加一些标记来跳过部分持续集成。看见 持续集成 。

请求将您的更改与主回购合并

当您感觉工作完成时，您可以创建拉取请求(PR)。GitHub有一个很好的帮助页面，其中概述了 filing pull requests 。

如果您的更改涉及对API的修改或函数的添加/修改，则应该启动代码审查。这涉及到将电子邮件发送到 SciPy mailing list 带有到你的公关的链接，以及对你的改变的描述和动机。

提交请购单前的核对表

• 您检查过代码是否可以在BSD许可下分发吗？看见 许可证注意事项 。

• 有没有代码覆盖率很好的单元测试？看见 NumPy/SciPy Testing Guidelines 。

• 所有单元测试都在本地通过吗？看见 在本地运行SciPy测试 。

• 是否所有公共函数都有包含示例的文档字符串？请参阅 numpydoc docstring guide 。

• 文档呈现是否正确？看见 使用Sphinx渲染文档 。

• 代码样式正确吗？看见 PEP8和SciPy 。

• 有没有基准？看见 用空速对SciPy进行基准测试 。

• 是提交消息 formatted correctly ？

• 标记为的新功能的文档字符串 .. versionadded:: X.Y.Z (其中 X.Y.Z 下一版本的版本号是多少？请参阅 updating ， workers ，以及 constraints 文档记录 differential_evolution, 例如。您可以从最新的发行说明中获取下一个版本号，网址为 the wiki 或从 MAJOR 和 MINOR 中的版本号变量 setup.py.

• 如果增加了更多内容，是否有教程或更广泛的模块级描述？教程文件位于 doc/source/tutorial 。

• 如果添加了编译后的代码，它是否通过 setup.py ？看见 编译后的代码 了解更多信息。

上一页

开发环境快速入门指南(Ubuntu)

下一页

PEP8和SciPy