初始流程

要開發開源專案首先必須先 Fork Repository ，因為不是自己的專案，我們沒有寫入權限。

Fork 完之後會有一個一模一樣的 Repository 出現在自己的帳號底下，我們通常把原本的專案叫做 upstream repo，自己 fork 過來的叫做 downstream repo。

自己 fork 過來的 Repository 我們就有寫入權限了，首先先把他 clone 下來 ，注意是 clone 自己 fork 過來的 repo，不是 upstream repo 。

假設我們要貢獻 kuberay 這個專案，而自己的 GitHub 名稱叫做 MortalHappiness，那麼 upstream repo 的 URL 會是 https://github.com/ray-project/kuberay.git，而自己 fork 出來的 repo URL 應該會是 [email protected]:MortalHappiness/kuberay.git（SSH）或是 https://github.com/MortalHappiness/kuberay.git（HTTPS）。假設我們使用 SSH。

Clone 下來之後可以執行 git remote -v，應該會長得像下面這樣：

origin  [email protected]:MortalHappiness/kuberay.git (fetch)
origin  [email protected]:MortalHappiness/kuberay.git (push)

接著需要添加 upstream remote，執行以下指令：

1
2

git remote add upstream https://github.com/ray-project/kuberay.git
git remote set-url --push upstream no_push

上面的指令第 1 行的 URL 要換成想貢獻的專案的 upstream URL。第 2 行則是避免我們不小心 push 到 upstream repo 上面。（其實我們也沒有寫入權限，本來就不能 push，但是說不定有一天我們做得很好，變成了 Committer 之後就有寫入權限了，加上這行可以避免我們不小心 push 到 upstream。

再次執行 git remote -v 應該會像下面這樣：

origin  [email protected]:MortalHappiness/kuberay.git (fetch)
origin  [email protected]:MortalHappiness/kuberay.git (push)
upstream        https://github.com/ray-project/kuberay.git (fetch)
upstream        no_push (push)

接下來下面這個是我個人的習慣，不一定需要這樣，為了避免不小心在 master branch（或 main branch）上面開發功能，我會創一個 local branch 去 track upstream/master branch，然後把 local 的 master branch 砍掉。

1
2
3

git fetch upstream
git checkout -b upstream-master upstream/master
git branch -d master

如果有在用 GitHub CLI ，可以順便把 default repo 設成 upstream。

1

gh repo set-default https://github.com/ray-project/kuberay.git

上面指令的 URL 記得換成自己的 upstream URL。

開發新功能流程

  1. 確保 local 的 upstream-master branch 和 remote 是同步的：

    1
2

    git checkout upstream-master
git pull upstream master

  2. Checkout 出新的 branch，假設叫做 feature/example：

    1

    git checkout -b feature/example upstream-main

  3. 正常開發（add、commit、push）。

  4. 去 upstream repo 開 pull request 。

同步 Upstream

假設開發到一半，upstream repo 有新的 commits，這時就需要同步 upstream，執行 git pull upstream master。

Sign-off Commits

有些開源專案會要求每個 commit 都必須被 sign-off，也就是說執行 git commit 的時候必須加上 -s 的 flag，變成 git commit -s。效果是會在 commit message 的最後加上一行 Sign-off-by。所以 commit message 會變得像下面這樣：

Some commit message.

Signed-off-by: Chi-Sheng Liu <[email protected]>

注意這邊的 sign-off 和 GPG-signed commits 是不一樣的。

如果 commit 的時候忘記加上 -s 的 flag，可以參考 這個連結 去補救。

如果覺得每次都要加 -s 這個 flag 很麻煩，可以使用 commit-msg hook：

把上面的內容寫到 .git/hooks/commit-msg 裡面，然後執行 chmod +x .git/hooks/commit-msg 即可。