开发工作流程#

注意：建议在阅读之前或之后观看 SciPy 开发工作流程 ，以了解修复错误和提交拉取请求的示例。

本指南假设您已创建了自己的 SciPy 仓库副本（fork），在您的机器上克隆了该仓库，并从该源代码构建了 SciPy。如果您还没有这样做，请查阅适用于您系统的从源代码构建页面。在开始此处的工作之前，您还需要做两件只需一次的事情，然后才能开始修改 SciPy。

在终端中，向 Git 介绍自己
```
git config --global user.email you@yourdomain.com
git config --global user.name "Your Name"
```
此信息将您的工作归功于您，但请注意，如果您将工作“推送”到 GitHub，此信息将公开可用。有关更多信息，请参阅在 Git 中设置您的提交电子邮件地址。
导航到您的本地 SciPy 仓库的根目录并输入
```
git remote add upstream https://github.com/scipy/scipy.git
```
这会将名称 upstream 与位于 scipy/scipy.git 的官方 SciPy 仓库关联起来。请注意，当您克隆您的 SciPy 仓库的 fork 时，Git 已经将名称 origin 与您的 fork 关联起来。您需要这两个“远程”的原因是，您通常会从官方仓库 upstream 获取最新版本的 SciPy，进行更改，将您的更改“推送”到您的仓库 origin 的 fork，然后提交“拉取请求”，请求 SciPy 将您的更改从您的 fork“拉取”到官方仓库中。
初始化 git 子模块
```
git submodule update --init
```
这将获取并更新 SciPy 所需的任何子模块（例如 Boost）。

基本工作流程#

简而言之

为您所做的每组编辑启动一个新的功能分支。请参阅下文。
尽情编写！请参阅下文。
完成后
- 贡献者：将您的功能分支推送到您自己的 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

按顺序，这些命令

确保已检出您本地仓库的 main 分支，
将 upstream/main（主 SciPy 仓库的主分支）的所有最新更改应用到您的本地 main 分支，并且
基于您的本地 main 分支创建并检出（-b）一个新分支。

无论如何，重要的是您的功能分支应包含来自上游主分支的最新更改，以帮助避免在提交拉取请求时发生合并冲突。

在继续之前，构建此分支并运行测试也是一个好主意。假设您已经按照从源代码构建页面之一设置了您的开发环境，您需要激活您的开发环境，然后运行测试（请注意，spin test 命令将根据需要自动执行构建）

conda activate scipy-dev
spin 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

更详细地#

进行一些更改。当您觉得您已经完成了一组完整的、可工作的相关更改时，请继续下一步。

可选：使用 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 modified_file 添加任何相关的已修改或新文件（参阅 git add）。这会将文件放入暂存区，这是一个将添加到您的下一个提交的文件队列。只添加具有相关、完整更改的文件。将具有未完成更改的文件留待以后提交。
要将暂存的文件提交到您的仓库的本地副本，请执行 git commit。此时，将打开一个文本编辑器，允许您编写提交消息。阅读提交消息部分以确保您正在编写格式正确且足够详细的提交消息。保存消息并关闭编辑器后，您的提交将被保存。对于琐碎的提交，可以使用 -m 标志通过命令行传递短提交消息。例如，git commit -am "ENH: Some message"。

在某些情况下，您会看到这种形式的提交命令：git commit -a。额外的 -a 标志会自动提交所有已修改的文件并删除所有已删除的文件。这可以节省您输入大量 git add 命令的麻烦；但是，如果您不小心，它可能会将不需要的更改添加到提交中。有关更多信息，请参阅为什么使用 -a 标志？ - 以及混乱的工作副本问题中 helpful use-case description。
将更改推送到您在 github 上的 fork 仓库
```
git push origin my-new-feature
```
有关更多信息，请参阅 git push。

注意

假设您已遵循这些页面中的说明，git 将创建一个名为 origin 的默认链接到您的 github 仓库。在 git >= 1.7 中，您可以使用 --set-upstream 选项确保永久设置到 origin 的链接

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

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

git push

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

可能在您进行编辑时，upstream 中添加了影响您工作的新提交。在这种情况下，请遵循在主分支上变基说明将这些更改应用到您的分支。

编写提交消息#

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

示例

MAINT/TST: fft: remove xp backend skips, test `fftfreq` `device`

The first line of the commit message starts with a capitalized acronym
(or multiple, options listed below) indicating what type of commit this is.
Then a blank line, then more text if needed.
References to code names should be enclosed in backticks.
If changes are limited to certain submodules or functions, they should be
included after the acronym(s) - backticks are not needed here.

示例

BUG:sparse.linalg.gmres: add early exit when `x0` already solves problem

Lines shouldn't be longer than 72 characters. If the commit is related to an issue,
indicate that with "See gh-3456", "Closes gh-3456", or similar,
in the extended description.
However, if you are pushing many commits to a PR, you should avoid including
this in every commit message as it will clutter the linked issue.

描述更改的动机、错误修复的错误性质或增强功能的一些细节也应包含在提交消息中。消息应该在不查看代码更改的情况下可理解。像 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。
是否有基准测试？请参阅使用 airspeed velocity 对 SciPy 进行基准测试。
提交消息格式是否正确？请参阅编写提交消息。
新功能的文档字符串是否带有 .. versionadded:: X.Y.Z 标记（其中 X.Y.Z 是下一个版本的版本号）？例如，请参阅 differential_evolution 的 updating、workers 和 constraints 文档。
如果添加了较大的内容，是否有教程或更广泛的模块级描述？教程文件位于 doc/source/tutorial 中。
如果添加了新文件，它们是否通过 meson.build 正确集成？有关更多信息，请参阅编译代码。