开发流程#

注意：建议在阅读之前或之后观看 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 仓库的副本时，Git 已将 origin 与您的副本关联。您需要这两个 “远程仓库” 的原因是，您通常会从官方仓库 upstream 的最新版本开始，进行更改，“推送”更改到您对仓库的副本 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

然后，基于 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)。

在任何情况下，重要的是您的功能分支包含来自 upstream 主分支的最新更改，这有助于避免在提交拉取请求时出现 合并冲突。

在继续之前，构建此分支并运行测试也是一个好主意。假设您已按照 从源代码构建 页面中的说明设置了开发环境，则您需要激活开发环境并运行测试（请注意，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 上变基 指示将这些更改应用到您的分支。

编写提交消息#

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

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 之前的检查清单#

本页内容