开发工作流程

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

本指南假定您已经创建了自己的 SciPy 仓库的 fork（副本），将该仓库克隆到您的机器上，并从源代码构建了 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 仓库的 fork 时，Git 已经将名称 origin 与您的 fork 关联起来。您需要这两个“远程仓库”的原因是，您通常会从官方仓库 upstream 获取最新版本的 SciPy，然后进行更改，将您的更改“推送”到您的仓库 fork origin，然后提交“拉取请求”，请求 SciPy 将您的更改从您的 fork “拉取”到官方仓库中。

3. 初始化 git 子模块

   git submodule update --init
   

   这会获取并更新 SciPy 所需的任何子模块（例如 Boost）。

基本工作流程

简而言之

1. 对于您进行的每组编辑，请启动一个新的特性分支。详情请参阅下方。

2. 尽情修改吧！详情请参阅下方。

3. 完成后

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

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

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

另请参阅

有许多在线教程可以帮助您学习 Git。关于特定 Git 工作流程的讨论，请参阅这些关于Linux Git 工作流程和IPython Git 工作流程的讨论。

创建新的特性分支

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

git fetch upstream

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

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

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

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

这些命令按顺序执行以下操作

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

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

3. 基于您的本地 main 分支创建并检出（-b）一个新分支。

无论如何，您的特性分支包含来自上游 main 分支的最新更改非常重要，这有助于在提交拉取请求时避免合并冲突。

在继续之前，构建此分支并运行测试也是个好主意。假设您已经按照从源代码构建页面之一设置了开发环境，您需要激活您的开发环境，然后运行测试（请注意，如果需要，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: Some message"。

   在某些情况下，您会看到这种形式的提交命令：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 分支相关联。此后，后续的 push 调用将简化为如下所示

git push

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

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

编写提交消息

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

示例

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 以进行开发。

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

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

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

• 是否有基准测试？请参阅使用 airspeed velocity 对 SciPy 进行基准测试。

• 提交消息格式是否正确？

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

• 如果添加了较大功能，是否有教程或更详细的模块级描述？教程文件位于 doc/source/tutorial。

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