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

然后，基于 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 将创建指向您 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 之前的清单#

本页内容