Attention: Here be dragons

This is the latest (unstable) version of this documentation, which may document features not available in or compatible with released stable versions of Godot.

Checking the stable version of the documentation...

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.

问题管理

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.

标签

The following labels are currently defined in the Godot repository:

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 报告)确认. 该标签的目的是让开发人员知道当他们想要选择要解决的问题时仍然可以重现的问题. 因此, 在一个评论中添加评论: 可以再现该问题的是什么平台, 什么版本或Godot的提交是一个好的做法；如果开发人员在一年后查看该问题, 则 Confirmed 标签可能不再相关.

  • Crash：用于描述导致引擎崩溃的问题。这个标签仅适用于“硬”崩溃，卡死不算。

  • Discussion: 这个问题不是共识, 需要进一步讨论以定义解决该主题的确切方法.

  • Documentation: related to the documentation. PRs with this label improve the class reference. Issues with this label are either for wrong documentation, or are user-reported "bugs" that are actually limitations to be further documented. Often paired with Discussion. Issues related to the ReadTheDocs documentation should be filed on the godot-docs repository.

  • 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：该问题需要在拉取请求会议中进行讨论。会议是公开的，在 Godot 贡献者聊天中举行。

  • Good first issue：该问题应该是易于修复的，非常适合想要熟悉代码库的新贡献者。有可用的 PR 能够解决该问题时应当移除此标签。

  • High priority：该问题非常重要，可能导致人们无法发布他们的项目或造成数据丢失。

  • Needs testing: 问题/拉取请求无法完全测试, 因此需要进一步测试. 这可能意味着需要在不同的硬件/软件配置上进行测试, 或者甚至重现的步骤不确定.

  • Needs work: the pull request needs additional work before it can be merged. Also for issues that are very incomplete, such as missing reproduction steps.

  • Performance: 直接影响引擎或编辑器性能的问题。也可用于改善性能或增加低端友好选项的拉取请求。不应与 Usability 可用性结合在一起。

  • Regression: 在没有表现出该错误的稳定版本发布之后，该错误出现。

  • 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: 用于跟踪其他问题的问题(例如与插件系统相关的所有问题).

  • 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: relates to the audio features (low- and high-level).

  • Buildsystem：与构建相关的问题，可以是与 Scons 构建系统相关，也可以是与编译器特性相关。

  • Codestyle：与代码库所使用的编程风格有关。

  • Core：任何与核心引擎相关的话题。特定的话题增长到一定程度就会拆分出来。

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

  • Editor：与编辑器中的问题（主要是 UI）有关。

  • Export：与导出系统和模板有关。

  • GDExtension：与原生扩展 GDExtension 系统相关。

  • GDScript：与 GDScript 相关。

  • GUI：与 GUI（Control）节点相关或与构成用户界面的 Node 相关。

  • Import：与资源导入系统有关。

  • Input：与输入系统相关。

  • I18n: relates to internationalization.

  • Multiplayer：与多人系统（高阶网络）相关。

  • Navigation：与导航系统（包括 A* 和导航网格）有关。

  • Network: relates to (low-level) networking.

  • Particles：粒子和粒子系统，以及对应的编辑器。

  • Physics：与物理引擎（2D/3D）有关。

  • Plugin：与编写插件时遇到的问题有关。

  • Porting：与某些特定平台或导出项目有关。

  • Rendering：与 2D 和 3D 渲染引擎有关。

  • Shaders：与 Godot 着色器语言或可视化着色器有关。

  • Tests：与单元测试有关。

  • Thirdparty：与 Godot 所使用的第三方库有关。

  • XR：与增强现实（AR）或虚拟现实（VR）有关。

问题通常只对应一个主题, 但看到符合两个主题的问题并不是不可想象的. 一般的想法是, 将有专门的贡献者团队支持所有主题, 因此他们可以专注于标记为团队主题的问题.

Platforms:

Android, iOS, LinuxBSD, macOS, Web, Windows

默认情况下, 假定给定的问题适用于所有平台. 如果使用其中一个平台标签, 则它不是通用的, 之前的假设不再适用(因此, 如果它是例如Android和Linux上的错误, 请选择这两个平台).

文档标签

In the documentation repository, we use the following labels:

  • Archived: 是另一个问题的副本, 或无效. 这样的问题也将被关闭.

  • Bug：现有页面中的错误信息。请勿对缺失信息使用。

  • Cherrypick：用于描述合并入 master 分支后还可以移植回稳定分支的内容。

  • Dependencies: describes pull requests that update a dependency file.

  • Discussion: 这个问题不是共识, 需要进一步讨论以定义解决该主题的确切方法.

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

  • 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：拉取请求需要额外处理才能进行合并。

  • Python: Pull requests that update Python code.

  • Salvageable: 由于设计问题或合并冲突，该拉动请求不能被合并，其作者也不再活跃。然而，它仍然可以被一个外部贡献者拾取，以使其达到可合并状态。为此，你需要基于原始拉取请求打开一个新的拉取请求。

  • Tracker: 用于跟踪其他问题的问题(例如与插件系统相关的所有问题).

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

Area:

  • About: Issues and PRs related to the About section of the documentation and other general articles.

  • Class reference：类参考的问题，非文档页面。

  • Community: Issues and PRs related to the Community section of the documentation.

  • Contributing: Issues and PRs related to the Contributing/Development section of the documentation.

  • Getting started: Issues and PRs related to the Getting Started section of the documentation.

  • Manual: Issues and PRs related to the Manual/Tutorials section of the documentation.

Content:

  • Images: Issues and PRs involving outdated or incorrect images in articles.

  • Example code: Issues and PRs involving writing or updating code examples.

  • New page: Issues and PRs related to creation of new documentation pages for new or undocumented features.

  • Organization: Issues and PRs related to reorganizing the content.

  • Proofreading: Issues and PRs related to proofreading the documentation.

  • Redirect: Issues and PRs involving moving content and adding a redirect rule on the backend.

  • Website: Issues related to adding website features and fixing bugs, whether on the front or back-end,

Topic:

The available topics describe the same content as the topics in the main repository.

里程碑

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.