Richtlinien für die Bug-Behebung

Diese Seite beschreibt den typischen Workflow des Bug-Analyse-Teams, auch Bugsquad genannt, bei der Bearbeitung von Problemen und Pull Requests auf Godots GitHub Repository. Sie wird sich zusammen mit dem Bugsquad weiterentwickeln - zögern Sie also nicht, Änderungen an den folgenden Richtlinien vorzuschlagen.

Issue-Management

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.

Labels

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: beschreibt etwas, das nur behoben werden kann, indem die Kompatibilität mit bestehenden Projekten gebrochen wird.

  • Bug: beschreibt etwas, das nicht richtig funktioniert.

  • Cherrypick: beschreibt etwas, das in einen stable Branch zurückportiert werden kann, nachdem es in den master-Branch eingefügt wurde.

  • Confirmed: wurde durch mindestens einen anderen Mitwirkenden als den Bug-Reporter bestätigt (typischerweise für Bug-Reports). Der Zweck dieses Labels besteht darin, die Entwickler wissen zu lassen, welche Probleme noch reproduzierbar sind, wenn sie auswählen wollen, woran sie arbeiten sollen. Es ist daher gute Praxis, einen Kommentar hinzuzufügen, auf welcher Plattform und in welcher Version oder Commit von Godot die Issue reproduziert werden konnte; wenn ein Entwickler die Issue ein Jahr später betrachtet, ist das Label Confirmed möglicherweise nicht mehr relevant.

  • Crash: beschreibt einen Bug, der die Engine zum Absturz bringt. Dieses Label wird nur für "harte" Abstürze verwendet, nicht für Freezes.

  • Discussion: Das Problem ist nicht einstimmig bewertet und bedarf weiterer Diskussion, um zu definieren, was genau getan werden soll, um das Thema anzugehen.

  • 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: Beschreibt eine vorgeschlagene Erweiterung einer vorhandenen Funktionalität.

  • 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: Das Problem muss in einem Pull Request-Meeting diskutiert werden. Diese Treffen sind öffentlich und werden im Godot-Mitwirkenden-Chat abgehalten.

  • Good first issue: Es wird angenommen, dass das Problem einfach zu beheben ist, was es für neue Mitwirkende, die sich mit der Codebasis vertraut machen wollen, sehr gut geeignet macht. Es sollte entfernt werden, solange ein aktiver PR verfügbar ist, der dieses Problem behebt.

  • High Priority: Das Problem ist besonders wichtig, da es Menschen daran hindern kann, ihre Projekte zu releasen, oder da es zu Datenverlust führen kann.

  • Needs testing: Die Issue oder der Pull Request konnte nicht vollständig getestet werden und bedarf somit weiterer Tests. Dies kann bedeuten, dass es auf verschiedenen Hardware-/Softwarekonfigurationen getestet werden muss oder dass die zu reproduzierenden Schritte nicht klar sind.

  • 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: Issues, die sich direkt auf die Performance der Engine oder des Editors auswirken. Kann auch für Pull Requests verwendet werden, die Godots Performance verbessern oder die Optionen für Low-End-Geräte hinzufügen. Sollte nicht gemeinsam mit Usability verwendet werden.

  • Regression: Der Bug trat auf, nachdem eine stable Version veröffentlicht wurde, die den Bug nicht aufwies.

  • 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, die verwendet wird, um andere Issues zu tracken (wie etwa alle Probleme im Zusammenhang mit dem Plugin-System).

  • Usability: Fragen, die sich direkt auf die Benutzerfreundlichkeit auswirken. Sollte nicht gemeinsam mit Performance verwendet werden.

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: bezieht sich auf das Animationssystem, die Editoren und Importer.

  • Assetlib: Bezieht sich auf Probleme mit der Asset-Bibliothek.

  • Audio: relates to the audio features (low- and high-level).

  • Buildsystem: bezieht sich auf Build-Issues, die entweder mit dem SCons-Buildsystem oder mit den Besonderheiten des Compilers zusammenhängen.

  • Codestyle: bezieht sich auf den in der Codebasis verwendeten Programmierstil.

  • Core: alles, was mit der Kern-Engine zu tun hat. Spezifische Themen werden separat behandelt, wenn sie auftauchen.

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

  • Editor: bezieht sich auf Probleme im Editor (hauptsächlich UI).

  • Export: bezieht sich auf das Exportsystem und die Export-Vorlagen.

  • GDExtension: bezieht sich auf das GDExtension-System für native Erweiterungen.

  • GDScript: bezieht sich auf GDScript.

  • GUI: bezieht sich auf GUI (Control)-Nodes oder auf Nodes zur Erstellung von Benutzeroberflächen.

  • Import: bezieht sich auf das System für den Import von Ressourcen.

  • Input: bezieht sich auf das Eingabesystem.

  • I18n: relates to internationalization.

  • Multiplayer: bezieht sich auf Multiplayer-Systeme (High-Level-Networking).

  • Navigation: bezieht sich auf das Navigationssystem (einschließlich A* und Navmeshes).

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

  • Particles: Partikel, Partikelsysteme und ihre Editoren.

  • Physics: bezieht sich auf die Physik-Engine (2D/3D).

  • Plugin: bezieht sich auf Probleme beim Schreiben von Plugins.

  • Porting: bezieht sich auf bestimmte Plattformen oder den Export von Projekten.

  • Rendering: bezieht sich auf die 2D- und 3D-Rendering-Engine.

  • Shader: bezieht sich auf die Godot-Shader-Sprache oder visuelle Shader.

  • Tests: bezieht sich auf Unit-Tests.

  • Thirdparty: bezieht sich auf Bibliotheken von Drittanbietern, die in Godot verwendet werden.

  • XR: bezieht sich auf Augmented Reality oder Virtual Reality.

Issues werden in der Regel nur einem Thema entsprechen, obwohl es nicht undenkbar ist, dass Issues zu zwei Themen passen. Der Grundgedanke ist, dass es für alle Themen spezialisierte Teams gibt, so dass sie sich auf die Themen konzentrieren können, die mit dem Thema ihres Teams gekennzeichnet sind.

Platforms:

Android, iOS, LinuxBSD, macOS, Web, Windows

Standardmäßig wird davon ausgegangen, dass eine bestimmte Issue für alle Plattformen gilt. Wenn eines der Plattform-Labels verwendet wird, ist es exklusiv und die vorherige Annahme gilt nicht mehr (wenn es sich also ausschließlich um einen Bug unter Android und Linux handelt, wählen Sie diese beiden Plattformen aus).

Dokumentations-Labels

In the documentation repository, we use the following labels:

  • Archived: entweder ein Duplikat einer anderen Issue oder ungültig. Eine solche Issue würde ebenfalls geschlossen werden.

  • Bug: Falsche Informationen auf einer bestehenden Seite. Nicht zu verwenden für fehlende Informationen.

  • Cherrypick: beschreibt etwas, das in einen stable Branch zurückportiert werden kann, nachdem es in den master-Branch eingefügt wurde.

  • Dependencies: beschreibt Pull Requests, die eine Abhängigkeitsdatei aktualisieren.

  • Discussion: Das Problem ist nicht einstimmig bewertet und bedarf weiterer Diskussion, um zu definieren, was genau getan werden soll, um das Thema anzugehen.

  • Enhancement: neue Informationen, die einer bestehenden Seite hinzugefügt werden sollen.

  • Good first issue: Es wird angenommen, dass das Problem einfach zu beheben ist, was es für neue Mitwirkende, die sich mit der Codebasis vertraut machen wollen, sehr gut geeignet macht. Es sollte entfernt werden, solange ein aktiver PR verfügbar ist, der dieses Problem behebt.

  • 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 Ihr erstes 2D-Spiel, need to update both repositories so that the tutorial code stays in sync with the completed demo.

  • Needs work: Der Pull Request benötigt zusätzliche Arbeit, bevor er gemergt werden kann.

  • Python: Pull Requests, die Python-Code aktualisieren.

  • Salvageable: der Pull Request kann aufgrund von Designproblemen oder Merge-Konflikten nicht gemergt werden und sein Autor ist nicht mehr aktiv. Sie kann jedoch immer noch von einem externen Mitwirkenden aufgegriffen werden, um sie in einen merge-fähigen Zustand zu bringen. Um dies zu tun, müssen Sie einen neuen Pull Request öffnen, der auf dem ursprünglichen Pull Request basiert.

  • Tracker: Issue, die verwendet wird, um andere Issues zu tracken (wie etwa alle Probleme im Zusammenhang mit dem Plugin-System).

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

Area:

  • About: Issues und PRs im Zusammenhang mit dem About-Abschnitt der Dokumentation und anderen allgemeinen Artikeln.

  • Class reference: Die Issue behandelt die Klassenreferenz, nicht eine Dokumentationsseite.

  • Community: Probleme und PRs, die sich auf den Community-Bereich der Dokumentation beziehen.

  • Contributing: Probleme und PRs, die sich auf den Abschnitt "Mitwirken/Engine-Entwicklung" der Dokumentation beziehen.

  • Getting started: Probleme und PRs im Zusammenhang mit dem Abschnitt "Erste Schritte" in der Dokumentation.

  • Manual: Probleme und PRs, die sich auf den Abschnitt "Handbuch" in der Dokumentation beziehen.

Content:

  • Images: Probleme und PRs im Zusammenhang mit veralteten oder falschen Bildern in Artikeln.

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

  • New page: Probleme und PRs im Zusammenhang mit der Erstellung neuer Dokumentationsseiten für neue oder undokumentierte Features.

  • Organization: Probleme und PRs im Zusammenhang mit der Umstrukturierung der Dokumentation.

  • Proofreading: Probleme und PRs im Zusammenhang mit dem Korrekturlesen der Dokumentation.

  • Redirect: Issues und PRs, die das Verschieben von Inhalten und das Hinzufügen einer Umleitungsregel im Backend betreffen.

  • Website: Fragen im Zusammenhang mit dem Hinzufügen von Website-Features und der Behebung von Bugs, sowohl im Front- als auch im Backend.

Topic:

Die verfügbaren Themen beschreiben denselben Inhalt wie die Themen im Haupt-Repository.

Milestones

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.