程式碼貢獻指南

貢獻方式

無論是文件、程式碼還是其他內容，都可以通過以下方式貢獻：

• Pull Request：提交程式碼到儲存庫，經過程式碼審查後合併到主分支
• Issue：提交問題或建議，經過討論後決定是否實作，並分配給開發者

程式碼貢獻流程

在提交程式碼之前請確保在本機完成了 Git 的全域設定。本機 Git 的提交電子信箱和使用者名稱需要和平台上註冊的電子信箱和使用者名稱保持一致，否則會產生錯誤的提交記錄，並無法計入貢獻者名單。

如果你不確定自己的電子信箱和使用者名稱是否正確，請在終端機檢視你的 Git 設定：

git config --global user.name
git config --global user.email

如果需要修改，可以使用以下命令，其中 "Your Name" 和 "your.email@example.com" 分別替換為你的使用者名稱和電子信箱：

git config --global user.name "Your Name"
git config --global user.email "your.email@example.com"

完成設定後，建議重新啟動終端機，以確保設定生效。

1. Fork 專案：點擊右上角 Fork 到自己的儲存庫
2. 建立分支：git checkout -b feature/your-feature
3. 提交更改：git commit -m "feat: 描述你的更改"
4. 推送分支：git push origin feature/your-feature
5. 提交 PR：建立 Pull Request

貢獻後的程式碼會經過程式碼審查，通過後合併到主分支。

GDScript 程式設計規範參考

本專案遵守 Godot 官方文件中的 GDScript 風格指南 的程式碼規範，以下是一些參考規範：

格式規範

• 縮排：使用 Tab 字元而非空白，每級縮排一個 Tab
• 行長度：控制在 100 字元以內，推薦 80 字元以下，不然容易影響閱讀
• 換行：使用 LF 換行，檔案末尾保留換行符號，避免 Git 衝突
• 編碼：UTF-8 無BOM，避免亂碼

一般來說使用 Godot 預設的腳本編輯器或者 VSCode 可以自動滿足這些格式規範，如果使用其他編輯器，請注意這些規範。

命名約定

元素類型	命名風格	範例
檔案名稱	snake_case	player_controller.gd
類別名稱	PascalCase	class_name PlayerController
函式/變數	snake_case	func move_player()
訊號	snake_case（過去式）	signal door_opened
常數	CONSTANT_CASE	const MAX_HEALTH = 100
列舉名稱	PascalCase	enum GameState
列舉值	CONSTANT_CASE	IDLE, RUNNING, JUMPING

腳本中只允許使用英文命名，不允許使用其他語言，避免出現問題。

註解規範

• 類別註解：每個類別頂部都需要註解，描述類別的功能和使用方法，這個註解會自動生成到文件中，請盡可能詳細
• 函式註解：每個公開函式頂部都需要註解，描述函式的功能、參數和回傳值，如果是私有函式，或者是內部工具函式，可以省略註解
• 變數註解：建議給必要的變數添加註解，特別是那些具有特定含義或用途的變數
• 訊號註解：每個訊號頂部都需要註解，描述訊號的用途和參數
• TODO 註解：如果需要添加待辦事項，請使用 TODO 註解，並描述待辦事項的內容和優先順序

提交規範

對於一個開源專案來說，提交資訊初期學習成本和適應過程確實需要一些努力，但它帶來的長期回報是巨大的。「嚴格」的資訊規範可以節省開發者之間理解和溝通時間，同時也為變更日誌（CHANGELOG）的生成提供了便利，使得變更日誌的生成更加規範。

Commit 資訊

本專案參考了 Conventional Commits 1.0.0 規範，具體格式如下：

<type>(<scope)>: <subject>

包括三個欄位：type（必需）、scope（可選）和 subject（必需）。

type（類型） 用於說明 commit 的類別，請使用以下標識之一：

類型	說明
feat	新功能（feature）
fix	修復 bug
docs	修改文件（documentation）
test	增加測試或修改現有測試
ci	對 CI 設定檔和腳本的更改

scope（範圍） 用於說明 commit 影響的範圍，視專案而定。例如可以是模組、元件、檔案等。

• feat(something): ...
• fix(ui): ...
• docs(readme): ...
• 如果影響範圍廣，可以省略或者使用(*)。

subject（主題） 是本次提交目的的簡短描述。

範例如下：

feat(xxx): 添加重播功能
fix: 修復了重播功能中重播速度過快導致程式當機的問題
docs(readme): 更新了 readme

Pull Request

PR（Pull Request）用於將你的程式碼提交到主儲存庫的主分支。在提交 PR 之前，請確保你的程式碼符合以下規範：

1. 程式碼格式規範，符合專案的程式碼風格。
2. 提交資訊規範，符合 Git Commit 資訊規範。
3. 提交的程式碼經過測試，無已知的問題。

如果以上條件基本滿足，就可以開始提交 PR 了。

PR 提交規範

PR 資訊需要包含以下內容：

1. 標題：簡潔明瞭地描述 PR 的內容，可以採用 Git Commit 資訊。
2. 描述：詳細描述 PR 的內容，包括實作功能說明、實作方式、影響範圍等。
3. issue 關聯：如果 PR 是針對某幾個 issue 的修復，請將 issue 的連結添加到 PR 資訊中。

其他建議

1. 為了節約維護者的時間和精力，PR 描述應盡可能詳細。
2. 除了簡單的 bug 修復或文字改動，都需要寫一篇像「短文」一樣的 PR 正文，最好鉅細靡遺。
3. 有時 PR 裡的 commit 內容需要修改，請隨時關注 PR 評論區裡的討論。
4. 並非所有 PR 都會被合併，在此提前向您表示抱歉。

程式碼評審

評審流程

在提交 PR 後，專案維護者會對程式碼進行評審。評審過程中，維護者可能會提出一些改進建議，包括但不限於程式碼風格、效能最佳化、安全性改進等。請認真閱讀和維護者提供的建議，並根據建議進行修改。

評審規範

在程式碼評審過程中，專案維護者將遵循以下規範：

1. 程式碼風格：確保程式碼風格符合專案的程式碼風格指南。
2. 效能最佳化：如果程式碼中有嚴重效能問題，請提供效能最佳化的方案。
3. 文件更新：如果程式碼修改會影響文件，請更新相應的文件。

尋求幫助

在大多數情況下，專案維護者將協助您解決程式碼評審過程中遇到的問題，確保您的程式碼能夠順利合併到主分支，如果需要幫助，請隨時關注 PR 評論區裡的討論。

申請成為維護者

在對專案做出一定 PR 貢獻後，將具有申請成為維護者的資格。如果您希望成為維護者，請按照以下步驟發送郵件申請：

1. 準備個人 Git 帳號資訊，包括使用者名稱、電子信箱，這將用於我們核對您的貢獻記錄以及後續發送邀請郵件。

2. 準備專案貢獻資訊，包括但不限於之前已經提交並合併的 PR 連結、參與討論的次數、回饋的 Issue 數量等。

3. 發送郵件至 konadoproject@163.com ，郵件主題為「申請成為 Konado 維護者」，郵件內容包含上述資訊。

4. 如果你願意，可以在郵件中附上你的個人簡介，包括你的興趣、技能和參與開源專案的經歷等，這樣可以讓我們更好地了解你。

專案維護者團隊將盡快回覆您的申請，並在確認您的貢獻記錄後，發送邀請郵件至您的電子信箱。請按照郵件中的指示完成維護者身分的確認以及儲存庫權限的設定。

希望你能成為我們 Konado 專案的一員，一起為開源社群做出貢獻！