跳转至

如何參與

在文章開始之前，OI Wiki 項目組全體成員十分歡迎您為本項目貢獻頁面。正因為有了上百位像您一樣的人，才有了 OI Wiki 的今天！

這篇文章將主要敍述參與 OI Wiki 編寫的寫作過程。請您在撰稿或者修正 Wiki 頁面以前，仔細閲讀以下內容，以幫助您完成更高質量的內容。

貢獻指南

請您在編輯前查看 OI Wiki 貢獻指南 和 項目方針，以更好地和社區貢獻者進行合作、交流。

參與協作

Warning

在開始編寫一段內容之前，請查閲 Issues，確認沒有別人在做相同的工作之後，開個 新 issue 記錄待編寫的內容。

在這裏引用維基百科的一句話：

不要害怕編輯，勇於更新頁面！1

在 GitHub 上編輯

參與 OI Wiki 的編寫 需要 一個 GitHub 賬號（可以前往 GitHub 的賬號註冊頁面 頁面註冊），但 不需要 高超的 GitHub 技巧，即使你是一名新手，只要按照下面所述的步驟操作，也能夠 非常出色 地完成編輯。

Tip

在你的更改被合併到 OI Wiki 的主倉庫之前，你對 OI Wiki 的內容所作出的修改均不會出現在 OI Wiki 的主站上，所以無需擔心你的修改會破壞 OI Wiki 上正在顯示的內容。

如果還是不放心，可以查看 GitHub 的官方教程。

編輯單個頁面內的內容

  1. 在 OI Wiki 上找到對應頁面；
  2. 點擊正文右上方（目錄左側）的 「編輯此頁」（edit）按鈕，在確認您已經閲讀了本頁面和 格式手冊 後點擊按鈕根據提示跳轉到 GitHub 進行編輯；
  3. 在編輯框內編寫你想修改的內容。請注意，在修改和接下來的提交過程中，請 關閉您的自動翻譯軟件，因為它可能產生不必要的麻煩（例如您修改的文件有時會被其錯誤改名，從而影響目錄結構）；
  4. 編寫完成後滾動到頁面下方，按照本文中 commit 信息格式規範 填寫 commit 信息，之後點擊 Propose changes 按鈕提交修改。點擊按鈕後，GitHub 會自動幫你創建一份 OI Wiki 倉庫的分支，並將你的提交添加到這個分支倉庫。
  5. GitHub 會自動跳轉到你的分支倉庫的頁面，此時頁面上方會顯示一個綠色的 Create pull request 按鈕，點擊後 GitHub 會跳轉到一個創建 Pull Request 頁面。向下滾動檢查自己所作出的修改沒有錯誤後，按照本文中 Pull Request 信息格式規範 一節中的規範書寫 Pull Request 信息，然後點擊頁面上的綠色的 Create pull request 按鈕創建 Pull Request。
  6. 不出意外的話，你的 Pull Request 就順利提交到倉庫，等待管理員審核併合併到主倉庫中即可。

在等待合併的時間裏，你可以給他人的 Pull Request 提意見、點贊或者點踩。如果有新消息，會在網頁右上角出現提示，並附有郵件提醒（取決於個人設置中配置的通知方式）。

編輯多個頁面內的內容

如果你需要同時編輯互相無關聯的多個頁面的內容，請按照上方的 編輯單個頁面內的內容 一節一次修改所有頁面。

  1. 打開 OI-Wiki/OI-Wiki 倉庫，點擊鍵盤上的.按鈕（或者將 URL 中的 github.com 更改為 github.dev）2，進入 GitHub 的網頁版 VS Code 編輯器；
  2. 在編輯器中作出對頁面源文件的更改，可以使用頁面右上方的預覽按鈕（或按下Ctrl+KV快捷鍵）在右側打開預覽界面；
  3. 修改完成後使用左側的 Source Control 選項卡，並按照本文中 commit 信息格式規範 填寫 commit 信息並提交，提交時會提示是否創建此倉庫的分支，點擊綠色的 Fork Repository 按鈕即可。
  4. 提交後會在網頁上方的中央彈出一個提示框，在第一次的提示框內填寫標題，第二次的提示框內填寫此提交要提交到的倉庫內分支名稱，之後右下角會彈出一個提示框，內容類似於 Created Pull Request #1 for OI-Wiki/OI-Wiki.，點擊藍字鏈接即可查看該 Pull Request。

向 Pull Request 追加更改

  1. 打開 OI-Wiki 的 Pull Request 列表，找到您提交的 Pull Request 並點擊。
  2. Pull Request 頁面的標題下方將會有一段例如 <您的ID> wants to merge x commits into OI-wiki:master from <您的ID>:patch-1 的文字，點擊 <您的ID>:patch-1 部分。
  3. 您應該會被重定向到您的分支倉庫中，而且文件列表左上角的分支名稱是你提交 Pull Request 的分支名稱（在本示例中應為 patch-1）。
  4. 進行您需要的更改。
    • 如果您需要編輯單個文件或多個互相無關聯的頁面的內容，請直接找到你要的文件並進行更改，更改完成後滾動到頁面下方，按照本文中 commit 信息格式規範 填寫 commit 信息，之後點擊 Commit changes 按鈕提交修改。
    • 如果您需要編輯多個文件，點擊鍵盤上的.按鈕（或者將 URL 中的 github.com 更改為 github.dev）2，進入 GitHub 的網頁版 VS Code 編輯器並作出更改。然後使用左側的 Source Control 選項卡，並按照本文中 commit 信息格式規範 填寫 commit 信息並提交修改。
  5. 這時你的更改會被自動追加在您的 Pull Request 中。

使用 Git 在本地進行編輯

Warning

對於一般用户，我們更推薦使用上方所述的 GitHub 的 Web 編輯器進行編輯。

雖然大多數情況下您可以直接在 GitHub 上進行編輯，但對於一些較為特殊的情況（如需要使用 GPG 簽名），我們更推薦使用 Git 在本地進行編輯。

大致流程如下：

  1. 將主倉庫 Fork 到自己的倉庫中；
  2. 將 Fork 後的分支倉庫克隆（clone）到本地；
  3. 在本地進行修改後提交（commit）這些更改；
  4. 將這些更改推送（push）到你克隆的分支倉庫；
  5. 提交 Pull Request 至主倉庫。

詳細的操作方式可以參考 Git 頁面。

向 Pull Request 追加更改

在 clone 下來的本地分支倉庫中繼續進行修改，並提交（commit）以及推送（push）這些更改即可。你的更改會被自動追加在 Pull Request 中。

在構建的網頁中預覽變更

在 Pull Request 頁面下方可以找到測試頁面，點擊 netlify/oi-wiki/deploy-preview 一項的 Details 鏈接（如下圖），可以進入自動構建的，由您變更後的頁面供您預覽。

deploy_preview

對於目錄和引用的變更

通常情況下，如果您需要添加一個新頁面，或者修改已有頁面在目錄中的鏈接，您就需要對 mkdocs.yml 文件作出改動。

添加新頁面可以參考既有的格式。但除非是進行重構或修正名詞，否則 我們不建議對既有頁面的引用鏈接進行修改，Pull Requests 中不必要的修改也將被駁回。

如果您堅持要修改鏈接，請注意更新 author 字段和重定向文件。

author 字段

GitHub API 在文件目錄變更後不能跟蹤統計，所以我們在文件頭手動維護了一個作者列表來解決這個問題。author 字段位於整個 Markdown 文件的開頭，形如 author: Ir1d, cjsoft，相鄰兩個 ID 之間用逗號加空格隔開。這裏的 ID 是 GitHub 的用户名，即 GitHub profile 的地址（例如 https://github.com/Ir1d 中的 Ir1d）。

修改鏈接時，需要將當前頁面中的 contributors 逐一填入 author 字段。

重定向文件

在修改鏈接時，為了避免在站外引用時出現死鏈，需要修改重定向文件。

_redirects 文件用於生成 netlify 的配置 和 用於跳轉的文件。

每一行表示一個重定向規則，分別寫跳轉的起點和終點的 url（不包含域名）：

1
/path/to/src /path/to/desc

注：所有跳轉均為 301 跳轉，只有在修改目錄中 url 造成死鏈的時候需要修改。

Commit 信息格式規範

對於提交時需要填寫的 commit 信息，請遵守以下幾點基本要求：

  1. commit 摘要請簡要描述這一次 commit 改動的內容。注意 commit 摘要的長度不要超過 50 字符，超出的部分會自動置於正文中。
  2. 如果需要進一步描述本次 commit 內容，請在正文中詳細説明。

對於 commit 摘要，推薦按照如下格式書寫：

1
<修改類型>(<文件名>): <修改的內容>

修改類型分為如下幾類：

  • feat：用於添加內容的情況。
  • fix：用於修正現有內容錯誤的情況。
  • refactor：用於對一個頁面進行重構（較大規模的更改）的情況。
  • revert：用於回退之前更改的情況。

Pull Request 信息格式規範

對於 Pull Request，請遵守以下幾點要求：

  1. 標題請寫明本次 PR 的目的（做了 什麼 工作，修復了 什麼 問題）。
  2. 內容請簡要敍述修改的內容。如果修復了一個 issue 的問題，請在內容中添加 fix #xxxx 字段，其中 xxxx 代表 issue 的編號。
  3. 請您仔細閲讀 貢獻指南 和 社區公約，並在同意後勾選 PR 模板中的框，表示您同意了以上指南和公約。

對於 Pull Request 的標題，推薦使用如下格式書寫：

1
<修改類型>(<文件名>): <修改的內容> (<對應 issue 的編號>)

修改類型分為如下幾類：

  • feat：用於添加內容的情況。
  • fix：用於修正現有內容錯誤的情況。
  • refactor：用於對一個頁面進行重構（較大規模的更改）的情況。
  • revert：用於回退之前更改的情況。

示例：

  • fix(ds/persistent-seg): 修改代碼註釋使描述更清晰
  • fix: tools/judger/index 不在目錄中 (#3709)
  • feat(math/poly/fft): better proof
  • refactor(ds/stack): 整理頁面內容

協作流程

  1. 在收到一個新的 Pull Request 之後，GitHub 會給 reviewer 發送郵件；
  2. 與此同時，在 GitHub Actions 和 Netlify 上會運行兩組測試，它們會把進度同步在 PR 頁面的下方。GitHub Actions 主要用來確認 PR 中內容的修改不會影響到網站構建的進程；Netlify 用來把 PR 中的更新構建出來，方便 reviewer 審核（在測試完成後點擊 Details 可以瞭解更多）；
  3. reviewer 可能會發現問題，並提出 review 或 suggested changes（建議更改，顯示為灰色圖標）/requested changes（強制更改，顯示為紅色圖標，只會在 reviewer 擁有 repo 寫權限時出現）。一般來説，reviewer 也會附上建議和需要進行的更改，在這時，您將會需要繼續向 Pull Request 追加其他更改。更改的方法可以參考 在 GitHub 上編輯 或者 使用 Git 在本地進行編輯 部分的 向 Pull Request 追加更改 部分。
  4. 在足夠多 reviewer 投票通過一個 PR 之後，這個 PR 才可以合併到 master 分支中；
  5. 在合併到 master 分支之後，GitHub Actions 會重新構建一遍網站內容，並更新到 gh-pages 分支；
  6. 這時服務器才會拉取 gh-pages 分支的更新，並重新部署最新版本的內容。

參考資料與註釋

  1. 維基百科：新手入門/編輯 ↩

  2. Web-based editor - GitHub Codespaces - GitHub Docs ↩↩

本页面最近更新：，更新历史
发现错误？想一起完善？ 在 GitHub 上编辑此页！
本页面贡献者：OI-wiki
本页面的全部内容在 CC BY-SA 4.0 和 SATA 协议之条款下提供，附加条款亦可能应用