Ctrl+K

开发工作流程#

注意：在阅读之前或之后，可以观看 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: Some message"。

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

  6. 将更改推送到 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 分支相关。随后的推送调用将简化为以下形式

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

本页内容