开发工作流程#

注意：在阅读前后考虑观看 SciPy 开发工作流程 以查看修复错误和提交拉取请求的示例。

本指南假设您已经创建了 SciPy 仓库的分支（副本），并在您的机器上克隆了该仓库，并从该源代码构建了 SciPy。如果您还没有这样做，请查看适用于您系统的 从源代码构建 页面。在开始这里之前，还有两件事您需要在开始修改 SciPy 之前只做一次。

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

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

    此信息将记录您的工作，但请注意，如果您将工作“推送”到GitHub，这些信息将公开可见。更多信息请参见 在Git中设置您的提交电子邮件地址。

  2. 导航到本地 SciPy 仓库的根目录并输入:

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

    这将与名称 upstream 与位于 scipy/scipy.git 的官方 SciPy 仓库关联。请注意，当您克隆了 SciPy 仓库的分支时，Git 已经将名称 origin 与您的分支关联。您需要这两个 “远程” 的原因是，您通常会从官方仓库 upstream 获取 SciPy 的最新版本，进行更改，将您的更改“推送”到仓库分支 origin，然后提交一个“拉取请求”，请求 SciPy 从您的分支“拉取”更改到官方仓库。

  3. 初始化 git 子模块:

    git submodule update --init

    这将获取并更新 SciPy 所需的所有子模块（如 Boost）。

基本工作流程#

简而言之：

  1. 每次进行编辑时，请为每个编辑集启动一个新的 功能分支 。请参见 下方 。

  2. 开始吧！见 下方。

  3. 完成时：

    • 贡献者: 将你的特性分支推送到你自己的 Github 仓库，并 创建一个拉取请求。

    • 核心开发者 如果你想在没有进一步审查的情况下推送更改，请参阅 下面的说明。

这种工作方式有助于保持工作井井有条，并尽可能清晰地记录历史。

参见

有许多在线教程可以帮助你 学习 git。关于特定 git 工作流的讨论，请参见这些关于 linux git 工作流 和 ipython git 工作流 的讨论。

创建一个新的功能分支#

首先，在终端中导航到 SciPy 的根目录，并从 upstream 仓库获取新的提交:

git fetch upstream

然后，基于上游仓库的主分支创建一个新分支:

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

同样地，你可能希望保持自己仓库的主分支是最新的，并基于此创建一个新分支:

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

按顺序，这些命令

  1. 确保你的本地仓库的 main 分支已被检出，

  2. 将 upstream/main``（SciPy 主仓库的主分支）中的所有最新更改应用到您的本地 ``main 分支，并

  3. 基于你的本地 main 分支创建并检出一个新分支 (-b)。

无论如何，重要的是你的特性分支应包含上游主分支的最新更改，以帮助避免在提交拉取请求时出现 合并冲突 。

在继续之前，构建此分支并运行测试也是一个好主意。假设你已经按照其中一个 从源代码构建 页面设置了你的开发环境，你需要激活你的开发环境，然后运行测试（注意，dev.py test 命令会在需要时自动执行构建）:

conda activate scipy-dev
python dev.py test -v

编辑工作流程#

概述#

# 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。此时，将打开一个文本编辑器，允许您编写提交信息。阅读 提交信息部分，以确保您编写了格式正确且足够详细的提交信息。保存信息并关闭编辑器后，您的提交将被保存。对于简单的提交，可以通过命令行使用 -m 标志传递简短的提交信息。例如，git commit -am "ENH: 一些信息"。

    在某些情况下，你会看到这种形式的提交命令：git commit -a。额外的 -a 标志会自动提交所有修改过的文件并删除所有已删除的文件。这可以节省你输入大量 git add 命令的时间；然而，如果你不小心，它可能会在提交中添加不需要的更改。更多信息，请参见 为什么使用 -a 标志？ - 以及 混乱的工作副本问题 中有用的用例描述。

  6. 将更改推送到你在 github 上的 fork 仓库:

    git push origin my-new-feature

    更多信息，请参见 git push。

备注

假设你已经按照这些页面中的说明操作，git 将创建一个默认链接到你的 github 仓库，称为 origin。在 git >= 1.7 中，你可以通过使用 --set-upstream 选项来确保链接到 origin 是永久设置的:

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

从现在开始，git 将知道 my-new-feature 与您自己的 github 仓库中的 my-new-feature 分支相关。随后的推送调用简化为以下内容:

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有一个很好的帮助页面，概述了 提交拉取请求 的过程。

如果你的更改涉及对API的修改或函数的添加/修改，你应该发起代码审查。这包括向 SciPy论坛 发送一封电子邮件，附上你的PR链接以及对更改的描述和动机。

提交PR前的检查清单#

  • 你检查过代码是否可以在BSD许可证下分发吗？请参阅 许可证注意事项。

  • 是否有单元测试具有良好的代码覆盖率？请参阅 NumPy/SciPy 测试指南。

  • 所有单元测试都在本地通过了吗？请参见 为 SciPy 开发从源代码构建。

  • 所有公共函数都有包含示例的文档字符串吗？请参阅 numpydoc 文档字符串指南。

  • 文档是否正确渲染？请参阅 使用 Sphinx 在本地渲染文档。

  • 代码风格正确吗？请参阅 PEP8 和 SciPy。

  • 有基准测试吗？请参见 使用asv进行基准测试。

  • 提交信息 格式正确吗？

  • 新功能的文档字符串是否标记为 .. versionadded:: X.Y.Z （其中 X.Y.Z 是下一个版本的版本号？例如，请参阅 differential_evolution 的 updating、workers 和 constraints 文档。

  • 对于较大的添加内容，是否有教程或更详细的模块级描述？教程文件位于 doc/source/tutorial。

  • 如果添加了新文件，它们是否通过 meson.build 正确集成？更多信息请参见 编译代码。

On this page