Bug 分級方針

This page describes the typical workflow of the bug triage team aka bugsquad when handling issues and pull requests on Godot's GitHub repository. It is bound to evolve together with the bugsquad, so do not hesitate to propose modifications to the following guidelines.

Issue 管理

GitHub 提供了各種管理 Issue 的功能：

  • 從預先定義的列表中設定一個或多個 Label (標籤)

  • 從預先定義的列表中設定 Milestone (里程碑)

  • 在專案 Dashboard (儀表板) 中持續追蹤 Issue

  • 將 Godot Engine 組織成員中其中一位貢獻者設定為「Assignee (負責人)」

由於 Godot Engine 在 GitHub 上的組織目前還只有有限的貢獻者，因此我們還沒很常用到負責人的功能。歡迎所有貢獻者參與，當遇到相關問題時在 Issue 上提出並與其他開發人員討論是解決問題最好的方法。。

For the time being, we do not use the project dashboard feature either.

我們會儘量給 Issue 與 PR 上加上 Label (必要的時候也會加上 Milestone)。

Label (標齊)

在 Godot 儲存庫中目前有設定下列 Label：

分類：

  • Archived: 封存。可能是與其他 Issue 重複或無效的 Issue。這種 Issue 也會被 Close (關閉)。

  • Breaks compat: describes something that can only be fixed by breaking compatibility with existing projects.

  • Bug: 代表某東西沒有正常運作。

  • Cherrypick: describes something that can be backported to a stable branch after being merged in the master branch.

  • Crash: describes a bug that causes the engine to crash. This label is only used for "hard" crashes, not freezes.

  • Confirmed: 已確認。由至少一位除了回報 Bug 的人以外的開發者確認 (通常用於 Bug 回報)。設定該 Label 是要讓其他開發人員在要處理 Issue 時知道那些 Issue 目前仍可重現。因此，在註解中寫上能復現該 Issue 的平台與 Godot 版本或 Commit 是好習慣。當某個開發人員過了一年之後回來看這個 Issue，則 Confirmed Label 可能不再適用。

  • Discussion: 討論。該 Issue 尚未取得共識，需要進一步討論以確認對於該議題確切該怎麼處理。

  • Documentation: 說明文件。與說明文件有關的 Issue。通常是要求要改進 API 說明文件。有關 ReadTheDocs 說明文件的 Issue 應開在 godot-docs 儲存庫內。

  • Enhancement: 改進。對現有功能的改進建議。

  • Feature proposal: describes a wish for a new feature to be implemented. Note that the main Godot repository no longer accepts feature requests. Please use godot-proposals instead.

  • For PR meeting: the issue needs to be discussed in a pull request meeting. These meetings are public and are held on the Godot Contributors Chat.

  • Good first issue: the issue is assumed to be an easy one to fix, which makes it a great fit for new contributors who need to become familiar with the code base.

  • High priority: the issue is particularly important as it can prevent people from releasing their projects or cause data loss.

  • Needs work: the pull request needs additional work before it can be merged.

  • Needs testing: 需要測試。該 Issue/PR 無法完整被測試，並需要進一步測試。這可能表示該 Issue 需要在不同的硬體或軟體設定上測試，甚至是測試所需要的重現步驟不一定的情況。

  • Performance: issues that directly impact engine or editor performance. Can also be used for pull requests that improve performance or add low-end-friendly options. Should not be coupled with Usability.

  • PR welcome / Hero wanted!: Contributions for issues with these labels are especially welcome. Note that this doesn't mean you can't work on issues without these labels.

  • Regression: the bug appeared after a stable release not exhibiting the bug was released.

  • 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 an external 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.

  • Tracker: 追蹤用。用來跟進其他 Issue 的 Issue (如所有與外掛系統有關的 Issue)。

  • Usability: issues that directly impact user usability. Should not be coupled with Performance.

這些分類用來對 Issue 進行一般性的分級。當有必要是這些 Label 也可能會組合使用，如某個用於提升可用性的 Issue 可以同時被標上 Enhancement 與 Usability。某個未達共識或描述不夠精確的功能請求會同時被標上 Feature proposal 與 Discussion。

主題：

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

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

  • Assetlib: 與素材庫有關的 Issue。

  • Audio: 與音訊功能有關的 Issue (不論低階或高階)。

  • Buildsystem: 與建置有關的 Issue，可能與 SCons 建置系統或其他特定編譯器有關。

  • Codestyle: relates to the programming style used within the codebase.

  • Core: 任何與核心引擎有關的 Issue。如果是足夠大的主題，可能會進一步被拆分成多個 Issue。

  • Editor: 與編輯器有關的 Issue (主要為 UI)。

  • GDNative: 與 GDNative 模組有關。

  • GDScript: 與 GDScript 有關。

  • GUI: relates to GUI (Control) nodes.

  • Import: relates to the resource import system.

  • Input: relates to input system.

  • Mono: 與 C# / Mono 繫結有關。

  • Navigation: relates to the navigation system (including A* and navmeshes).

  • Network: 與網路有關。

  • Physics: 與物理引擎有關 (2D/3D)。

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

  • Porting: relates to some specific platforms or exporting projects.

  • Rendering: 與 2D、3D 算繪引擎有關。

  • Shaders: relates to the Godot shader language or visual shaders.

  • Tests: relates to unit tests.

  • Thirdparty: relates to third-party libraries used in Godot.

  • VisualScript: relates to issues with the visual scripting language (not visual shaders).

  • XR: relates to Augmented Reality or Virtual Reality.

Issue 通常只會對應到一個主題，雖然很難想像會有 Issue 同時符合兩個主題。主要的概念是希望每個主題背後都有專門的貢獻者團隊，這樣這些團隊就能各自專注於標上該主題標籤的 Issue。

平台：

Android, HTML5, iOS, Linux, macOS, Windows, UWP

預設情況下，我們都假設某個 Issue 適用於所有平台。但如果使用了其中一個平台的 Label，則表示剛才這個假設不適用 (也就是如這個 Bug 是在 Android 或 Linux 上才會出現的，那麼就加上這兩個平台)。

Documentation labels

In the documentation repository, we use the following labels:

  • Bug: Incorrect information in an existing page. Not to be used for missing information.

  • Class reference: the issue is about the class reference, not a documentation page.

  • Discussion: 討論。該 Issue 尚未取得共識，需要進一步討論以確認對於該議題確切該怎麼處理。

  • Enhancememnt: new information to be added in an existing page.

  • New page: a new page to be created.

  • Hero wanted!: contributions for issues with these labels are especially welcome. Note that this doesn't mean you can't work on issues without these labels.

  • Organization: The issue involves moving pages around or reorganizing content.

  • Redirect: a redirection needs to be created in the Read the Docs backend. Only administrators can do this.

  • 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 an external 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.

  • Topic:Mono: the issue is about C# support in Godot.

  • Topic:Website: the issue relates to the Sphinx/Read the Docs frontend or backend, not the documentation contents.

Milestone (里程碑)

Milestone (里程碑) 對應到現有 Godot 藍圖中已計劃的未來版本。當有 Issue 符合這個藍圖中的計劃，則應該列在相應的 Milestone 中。如果是不對應任何目前藍圖的 Issue，就應該保持沒有 Milestone 的狀態。依照經驗法則，如果 Issue 涉及在 Milestone 中的新功能、任何絕對不該在未來穩定版更新中出現的 Bug、或是任何 Juan 馬上就想處理的東西，就該對應到相關 Milestone :)

不管 Issue 設定了什麼 Milestone，都歡迎貢獻者自由選擇 Issue 處理。若是某個不緊急且沒設定 Milestone 的 Bug 也依然歡迎處理。