Bug 分級指引

本頁描述 Bug 分級團隊（bugsquad）在 Godot 的 GitHub 倉庫 上處理 Issue 和 Pull Request 的標準流程。隨著 bugsquad 的發展，這些指引也會持續調整，歡迎隨時提出修正建議。

Issue 管理

For issue management, we use the following GitHub processes:

  • Each issue and pull request (PR) is categorized with a set of labels, sometimes called "tags".

  • Each PR is assigned to a milestone. Some issues can also be assigned to a milestone (see below).

  • Issues can have an assignee, who is a contributor among Godot maintainers.

  • Issues can be put in one or more projects.

  • PRs can be linked to one or more issues which they "fix" or "close".

We don't yet extensively use or rely on some other GitHub processes:

  • Issue close reasons (completed, not planned, duplicate). While we use these, it is not consistent, and older issues are all closed as "completed", so the issue close reason should not be relied on.

  • Issue types (Bug, Feature, Task).

  • Issue relationships.

We only use the assignees feature for Godot maintainers who are members of the Godot Engine GitHub organization, and even then not in all cases. For other issues, we track who is working on an issue by comments on the issue and linked pull requests. Most issues are available for any contributor to take on, after discussing it with other contributors. If you would like to work on an issue, first check that no one else is working on it, by looking for a linked pull request, a comment "claiming" the issue, or an assignee. If no one else is working on the issue, leave a comment on the issue to "claim" it and start working on it.

標籤（Label）

Godot 倉庫目前已定義下列 標籤：

Categories:

  • Archived: used to filter issues closed with a resolution other than "fixed".

    • For issues, added to all issues that are not resolved by engine or documentation changes. This includes duplicate issues, user error, or reports in the wrong repository. Since we don't rely on GitHub's issue close reasons (completed, not planned, and duplicate), it is possible for an issue to be closed as completed with the Archived label.

    • For PRs, added to all closed PRs that are not merged. This includes superseded or duplicate PRs, Git or GitHub mistakes, and valid PRs that end up not merged.

  • Breaks compat：描述只能通過破壞現有專案相容性來修復的問題。

  • Bug：描述未正常運作的問題。

  • Cherrypick：描述合併到 master 分支後仍可回溯到穩定分支的內容。

  • Confirmed：已確認。除回報者外，至少有一位其他貢獻者確認該 Bug（通常用於 Bug 報告）。這個標籤讓開發者能快速知道哪些問題目前仍可重現。建議在留言中註明可重現的平台與 Godot 版本或 Commit，若日後狀況改變，Confirmed 標籤可能就不再適用。

  • Crash：引擎發生當機（Crash）的問題。僅限「硬性當機」，不包括程式卡死（freeze）。

  • Discussion：此議題尚未有共識，需要進一步討論以決定如何處理。

  • Documentation：與說明文件相關。此標籤的 PR 用於改善類別參考文件。若是 Issue，則可能是文件錯誤，或是使用者回報的「Bug」實際上只是需要補充文件說明的限制。常與 Discussion 搭配。若是 ReadTheDocs 文件相關問題，請在 godot-docs 倉庫提出。

  • Enhancement：對現有功能的改善建議。

  • Feature proposal: used for PRs adding new features which do not have a corresponding proposal use this label. The label is removed when a feature proposal is created and linked. The main Godot repository no longer accepts feature requests as issues. Please use the godot-proposals repository instead.

  • For PR meeting：此議題需在拉取請求（PR）會議中討論。會議為公開舉行，地點在 Godot 貢獻者聊天室。

  • Good first issue：假設為容易修正的問題，適合新手貢獻者熟悉程式碼基礎。若已有解決該問題的 PR，應移除此標籤。

  • High priority：此問題極為重要，可能導致專案無法發佈或資料遺失。

  • Needs testing：此 Issue/PR 尚未完全測試，需要進一步測試。可能需於不同硬體/軟體設定下測試，或重現步驟尚不明確。

  • Needs work：此 PR 尚需補強才能合併。若 Issue 缺乏必要資訊（如重現步驟），也會使用本標籤。

  • Performance：直接影響引擎或編輯器效能的問題。也適用於提升效能或增加低階裝置友善選項的 PR。不應與 Usability 標籤同時使用。

  • Regression：此 Bug 在某個無此問題的穩定版發佈後才出現。

  • Salvageable: the pull request can't be merged due to design issues or merge conflicts and its author is not active anymore. However, it can still be picked up by another contributor to bring it to a mergeable state. To do so, you need to open a new pull request based on the original pull request.

  • Spam: intentional spam issues, and extremely low-effort PRs. Used sparingly, since we give contributors and users the benefit of the doubt. In most cases, Needs work or Archived is more appropriate.

  • Tracker：用於追蹤其他 Issue 的 Issue（如所有與外掛系統相關的議題）。

  • Usability：直接影響使用者體驗或可用性的問題。不應與 Performance 標籤同時使用。

The categories are used for general triage of the issues. They can be combined in some way when relevant, e.g. an issue can be labeled Bug and Usability at the same time if it's a bug that affects usability. Or Enhancement and Discussion if it's an improvement that requires discussion of the best approach. At least one of the categories Bug, Enhancement, or Discussion are used to describe an issue or pull request.

Topics:

  • 2D: relates to 2D nodes. Should be coupled with one of the labels below, and should not be coupled with 3D.

  • 3D: relates to 3D nodes. Should be coupled with one of the labels below, and should not be coupled with 2D.

  • Animation：與動畫系統、動畫編輯器與動畫匯入工具相關。

  • Assetlib：與素材庫相關的問題。

  • Audio：與音訊功能（包括低層與高層）有關的問題。

  • Buildsystem：與建置問題有關，可能涉及 SCons 建置系統或特定編譯器。

  • Codestyle：與程式碼風格有關的問題。

  • Core：與核心引擎相關的任何內容。若主題夠大會拆分為獨立議題。

  • Dotnet: relates to the C# / .NET bindings.

  • Editor：與 Godot 編輯器本身（主要是 UI）相關的問題。

  • Export：與匯出系統及匯出範本相關的問題。

  • GDExtension：與原生擴充功能 GDExtension 系統相關的問題。

  • GDScript：與 GDScript 腳本語言相關的問題。

  • GUI：與 GUI（Control 節點）或構成使用者介面之節點相關的問題。

  • Import：與資源匯入系統相關的問題。

  • Input：與輸入系統相關的問題。

  • I18n: relates to internationalization.

  • Multiplayer：與多人遊戲（高階網路系統）相關的問題。

  • Navigation：與尋路系統（包含 A* 與導航網格）相關的問題。

  • Network：與（低層）網路系統相關的問題。

  • Particles：與粒子、粒子系統及其編輯工具相關的問題。

  • Physics：與物理引擎（2D/3D）相關的問題。

  • Plugin：與撰寫外掛（Plugin）時遇到的問題有關。

  • Porting：與特定平台或專案移植相關的問題。

  • Rendering：與 2D、3D 算圖引擎相關的問題。

  • Shaders：與 Godot 著色器語言或視覺著色器相關的問題。

  • Tests：與單元測試相關的問題。

  • Thirdparty：與 Godot 使用的第三方函式庫相關的問題。

  • XR：與擴增實境（AR）或虛擬實境（VR）相關的問題。

Issue 通常僅對應單一主題，雖然偶爾也會有同時屬於兩個主題的情況。這樣分工能讓各主題專責團隊專注處理屬於自己領域的 Issue。

Platforms:

Android, iOS, LinuxBSD, macOS, Web, Windows

預設情況下，所有 Issue 都認為適用於所有平台。若有指派特定平台標籤，則僅限於該標籤所示平台（例如只在 Android 與 Linux 發生的 Bug，就要勾選這兩個平台）。

說明文件標籤

在 說明文件倉庫 中，我們使用下列 標籤：

  • Archived：重複或無效的 Issue，通常也會直接關閉。

  • Bug：現有頁面中的錯誤資訊。不適用於缺漏資訊。

  • Cherrypick：描述合併到 master 分支後仍可回溯到穩定分支的內容。

  • Dependencies：描述更新相依性檔案的 PR。

  • Discussion：此議題尚未有共識，需要進一步討論以決定如何處理。

  • Enhancement：於現有頁面新增內容。

  • Good first issue：假設為容易修正的問題，適合新手貢獻者熟悉程式碼基礎。若已有解決該問題的 PR，應移除此標籤。

  • Linked demo PR: the PR has a corresponding PR to the Godot Demo Projects repository which must be merged at the same time. Any changes to code in tutorials that have a corresponding demo, such as 您的第一個 2D 遊戲, need to update both repositories so that the tutorial code stays in sync with the completed demo.

  • Needs work：此 PR 尚需補強才能合併。

  • Python：更新 Python 程式碼的 PR。

  • Salvageable：由於設計問題或合併衝突，該 PR 目前無法合併，且原作者不再活躍。但外部貢獻者仍可接手，將其修正至可合併狀態。若要接手，請基於原 PR 開啟新 PR。

  • Tracker：用於追蹤其他 Issue 的 Issue（如所有與外掛系統相關的議題）。

  • Waiting on PR merge: the PR documents an engine PR that has not been merged yet.

Area:

  • About：與文件的「關於」區塊或一般文章相關的 Issue 或 PR。

  • Class reference：與類別參考（非一般文件頁面）相關的問題。

  • Community：與文件社群區塊相關的 Issue 或 PR。

  • Contributing：與文件「貢獻」/「開發」區塊相關的 Issue 或 PR。

  • Getting started：與文件「入門」區塊相關的 Issue 或 PR。

  • Manual：與文件「手冊」或「教學」區塊相關的 Issue 或 PR。

Content:

  • Images：涉及文章中過時或錯誤圖片的 Issue 或 PR。

  • Example code：涉及撰寫或更新程式碼範例的 Issue 或 PR。

  • New page：與建立新文件頁面（針對新功能或未記錄功能）相關的 Issue 或 PR。

  • Organization：與重新組織內容或移動頁面相關的 Issue 或 PR。

  • Proofreading：與校對文件內容相關的 Issue 或 PR。

  • Redirect：涉及移動內容與後端新設重定向規則的 Issue 或 PR。

  • Website ：與網站功能新增或 Bug 修正相關的 Issue，無論前端或後端，

Topic:

可用主題內容與主倉庫相同。

里程碑（Milestone）

Milestones are used for some issues and all PRs.

We have milestones for specific minor engine versions, like 4.5 and 4.6, as well as general milestones for major engine versions, like 3.x and 4.x. In the godot-proposals repo, we also have a 5.0 milestone for compatibility-breaking changes that will be considered for Godot 5.0, in many years.

Issues are assigned to the current development milestone, such as 4.5, if they are related to features introduced in that engine version, or are bugs (regressions) in that version. Additionally, all issues completed during the development of that engine version are added to the milestone, so that users can see at a glance in which minor version an issue was first fixed. We don't always use the 4.x milestone for issues, since by default all issues are related to Godot 4.x. However, we do use the 3.x milestone to mark issues that are specific to Godot 3.x.

All pull requests are assigned to a milestone. By default, enhancement and feature PRs are assigned to the 4.x milestone, and bugs are assigned to the current development milestone, such as 4.5. Towards the end of the minor version's development, PRs currently in that milestone are reassessed. If a PR is no longer being considered for that version, it is reassigned to either the major version milestone (4.x), or the next minor version milestone (such as 4.6).

Pull requests in the 4.x milestone are reassigned to the current minor engine version, such as 4.5, when the review process is complete, and the production team decides that the PR is ready to be merged soon. Note that this usually requires more than one approving review.

The milestone assigned to a PR is a goal, not a guarantee. New features and enhancements are merged when they are ready. While reviewers and maintainers do their best to review PRs in time for the current version, at some point we reach the beta, feature freeze, and then release; and existing PRs are reassigned to the next minor version, or to 4.x. As a rule, we assign new features to the 4.x milestone initially to avoid continually reassigning a PR from version to version. However, a PR being in 4.x does not mean it won't be merged; it's just the default for new features.