Bug triage guidelines

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.

Gestione dei problemi (issues)

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.

Etichette

Le seguenti etichette sono attualmente definite nel repository di 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: describes something that can only be fixed by breaking compatibility with existing projects.

  • Bug: describes something that is not working properly.

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

  • Confirmed: has been confirmed by at least one other contributor than the bug reporter (typically for Bug reports). The purpose of this label is to let developers know which issues are still reproducible when they want to select what to work on. It is therefore a good practice to add in a comment on what platform and what version or commit of Godot the issue could be reproduced; if a developer looks at the issue one year later, the Confirmed label may not be relevant anymore.

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

  • Discussion: the issue is not consensual and needs further discussion to define what exactly should be done to address the topic.

  • 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: describes a proposed enhancement to an existing functionality.

  • 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: 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 want to become familiar with the code base. It should be removed while an active PR is available, that resolves this issue.

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

  • Needs testing: the issue/pull request could not be completely tested and thus need further testing. This can mean that it needs to be tested on different hardware/software configurations or even that the steps to reproduce are not certain.

  • 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: problemi che hanno un impatto diretto sulle prestazioni del motore o dell'editor. Può anche essere usato per richieste di pull che migliorano le prestazioni o aggiungono opzioni di fascia bassa. Non dovrebbe essere accoppiato con Usabilità.

  • Regression: il bug è apparso dopo il rilascio di una versione stabile che non presentava il 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 used to track other issues (like all issues related to the plugin system).

  • Usabilità: problemi che hanno un impatto diretto sull'usabilità per l'utente. Non dovrebbe essere accoppiato con 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: si riferisce al sistema di animazione, agli editor e agli importatori.

  • Assetlib: si riferisce ai problemi con la libreria dei contenuti.

  • Audio: si riferisce alle funzionalità audio (basso e alto livello).

  • Buildsystem: si riferisce a problemi di compilazione, collegati al buildsystem di SCons o a peculiarità del compilatore.

  • Codestyle: si riferisce allo stile di programmazione utilizzato nel codice sorgente.

  • Core: tutto ciò che riguarda il motore principale. Gli argomenti specifici sono suddivisi separatamente man mano che si presentano.

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

  • Editor: si riferisce ai problemi dell'editor (principalmente l'interfaccia utente).

  • Esporta: si riferisce al sistema di esportazione e ai modelli.

  • GDExtension: si riferisce al sistema GDExtension per le estensioni native.

  • GDScript: si riferisce a GDScript.

  • GUI: si riferisce ai nodi GUI (Control) o ai nodi che compongono le interfacce utente.

  • Import: si riferisce al sistema di importazione delle risorse.

  • Input: si riferisce al sistema di input.

  • I18n: relates to internationalization.

  • Multiplayer: si riferisce ai sistemi multigiocatore (networking di alto livello).

  • Navigation: si riferisce al sistema di navigazione (inclusi A* e navmesh).

  • Network: si riferisce al networking (di basso livello).

  • Particelle: particelle, sistemi di particelle e relativi editor.

  • Physics: si riferisce al motore di fisica (2D/3D).

  • Plugin: si riferisce ai problemi riscontrati durante la scrittura delle estensioni.

  • Porting: si riferisce ad alcune piattaforme specifiche o l'esportazione di progetti.

  • Rendering: si riferisce ai motori di rendering 2D e 3D.

  • Shaders: si riferisce al linguaggio di shader di Godot o ai visual shader.

  • Tests: si riferisce ai test unitari.

  • Thirdparty: si riferisce alle librerie di terze parti utilizzate in Godot.

  • XR: si riferisce alla Realtà Aumentata (AR) o Realtà Virtuale (VR).

In genere, i problemi corrispondono a un solo argomento, anche se non è impensabile che si tratti di due argomenti. L'idea generale è che ci saranno team di collaboratori specializzati per ogni argomento, in modo che possano concentrarsi sui problemi etichettati con l'argomento del loro team.

Platforms:

Android, iOS, LinuxBSD, macOS, Web, Windows

By default, it is assumed that a given issue applies to all platforms. If one of the platform labels is used, it is then exclusive and the previous assumption doesn't stand anymore (so if it's a bug on e.g. Android and Linux exclusively, select those two platforms).

Etichette di documentazione

Nel repository della documentazione, utilizziamo le seguenti etichette:

  • Archived: either a duplicate of another issue, or invalid. Such an issue would also be closed.

  • Bug: Informazioni errate in una pagina esistente. Da non utilizzare per informazioni che mancano.

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

  • Dependencies: descrive le richieste di pull che aggiornano un file di dipendenza.

  • Discussion: the issue is not consensual and needs further discussion to define what exactly should be done to address the topic.

  • Enhancement: nuove informazioni da aggiungere a una pagina esistente.

  • Good first issue: the issue is assumed to be an easy one to fix, which makes it a great fit for new contributors who want to become familiar with the code base. It should be removed while an active PR is available, that resolves this issue.

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

  • Needs work: la richiesta di pull necessita di ulteriore lavoro prima di poter essere unita.

  • Python: richieste di pull che aggiornano il codice Python.

  • 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 used to track other issues (like all issues related to the plugin system).

  • 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: il problema riguarda il riferimento alle classi, non una pagina di documentazione.

  • 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: Problemi e PR relativi alla sezione Manuale/Tutorial della documentazione.

Content:

  • Images: Problemi e PR relativi a immagini obsolete o errate negli articoli.

  • Example code: Problemi e PR relativi alla scrittura o all'aggiornamento di esempi di codice.

  • New page: Problemi e PR relativi alla creazione di nuove pagine di documentazione per funzionalità nuove o non documentate.

  • Organization: Problemi e PR relativi alla riorganizzazione dei contenuti.

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

  • Redirect: problemi e PR relativi allo spostamento di contenuti e all'aggiunta di una regola di reindirizzamento nel backend.

  • Website: problemi relativi all'aggiunta di funzionalità al sito web e alla correzione di bug, sia nel front-end sia nel back-end,

Topic:

Gli argomenti disponibili descrivono lo stesso contenuto degli argomenti nel repository principale.

Pietre miliari

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.