開發工作流程#

注意：在閱讀之前或之後，可以考慮觀看 SciPy 開發工作流程 ，以查看修復錯誤並提交提取請求的範例。

本指南假設您已建立 SciPy 儲存庫的個人分支（副本）、在您自己的機器上克隆了該儲存庫，並從此原始碼建置了 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 儲存庫的分支時，Git 已經將名稱 origin 與您的分支關聯起來。您需要這兩個 “遠端” 的原因是，您通常會從官方儲存庫 upstream 中的最新版本的 SciPy 開始，進行更改，將您的更改「推送」到您的儲存庫分支 origin，然後提交「提取請求」，要求 SciPy 從您的分支「拉取」您的更改到官方儲存庫中。
初始化 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)。

在任何情況下，重要的是您的功能分支包含來自上游主分支的最新更改，以幫助避免在提交提取請求時發生合併衝突。

在繼續之前，建立此分支並執行測試也是一個好主意。假設您已按照從原始碼建置頁面之一設定您的開發環境，您需要啟動您的開發環境，然後執行測試（請注意，如果需要，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

更詳細地說#

進行一些更改。當您覺得您已完成一組完整的、可運作的相關更改時，請繼續執行下一步。

可選：使用 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 標誌？ - 以及混亂的工作副本問題中的有用用例描述。
將更改推送到您在 github 上的分支儲存庫
```
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，這會影響您的工作。在這種情況下，請按照在 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 開發環境。
所有公共函數是否都有包含範例的文件字串？請參閱 numpydoc 文件字串指南。
文件是否正確呈現？請參閱使用 Sphinx 在本地呈現文件。
程式碼風格是否正確？請參閱PEP8 和 SciPy。
有基準測試嗎？請參閱使用 airspeed velocity 基準測試 SciPy。
提交訊息是否格式正確？
新功能的文件字串是否標記了 .. versionadded:: X.Y.Z（其中 X.Y.Z 是下一個發行版本的版本號？例如，請參閱 differential_evolution 的 updating、workers 和 constraints 文件。
如果是較大的新增功能，是否有教學或更廣泛的模組級別描述？教學檔案位於 doc/source/tutorial 中。
如果新增了新檔案，它們是否透過 meson.build 正確整合？有關更多資訊，請參閱編譯程式碼。