程式碼貢獻指南

貢獻方式

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

• 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 編寫風格指南 程式碼規範，以下是一些參考規範：

格式規範

• 縮排：使用定位字元而非空格，每級縮排一個定位字元
• 行長度：控制在 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. 寄送郵件至 konado@godothub.com，郵件主旨為「申請成為 Konado 維護者」，郵件內容包含上述資訊。

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

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

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