Lignes directrices pour le triage des bogues

Cette page décrit le flux de travail typique de l'équipe de triage des bogues alias bugsquad lors de la gestion des problèmes et des pull requests sur le dépôt GitHub de Godot. Elle est appelée à évoluer avec le bugsquad, n'hésitez donc pas à proposer des modifications aux directives suivantes.

Gestion des 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.

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 : décris quelque chose qui ne peut être corrigé qu'en n'étant plus compatible avec les projets existants.

  • Bug : décrit quelque chose qui ne fonctionne pas correctement.

  • Cherrypick : décris quelque chose qui peut être repris de la branche master (principale) pour être intégrée dans la branche stable actuelle.

  • Confirmed : a été confirmée par au moins un autre contributeur que le rapporteur de bogue (généralement pour les rapports de bogue). L'objectif de ce label est de faire savoir aux développeurs quels problèmes sont encore reproductibles lorsqu'ils veulent choisir sur quoi travailler. C'est donc une bonne pratique que d'ajouter un commentaire sur la plate-forme et la version ou le commit de Godot sur lesquels le problème pourrait être reproduit ; si un développeur examine le problème un an plus tard, le label Confirmed peut ne plus être pertinent.

  • Crash : decris un bogue faisant planter le moteur de jeu. N'est utilisé que quand l'application quitte inopinément, et pas quand elle ne fait que se figer.

  • Discussion : la question n'est pas consensuelle et nécessite une discussion plus approfondie afin de définir ce qui doit être fait exactement pour traiter le sujet.

  • 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 : décrit une proposition d'amélioration d'une fonctionnalité existante.

  • 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 : le problème doit être discuté dans une réunion de pull request. Ces réunions sont publiques et se tiennent sur le 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 : ce problème a une _haut priorité_ car elle peut empêcher de publier des projets ou la perte de données.

  • Needs testing : l'issue ou la Pull Request n'a pas pu être complètement testée et doit donc être soumise à des tests supplémentaires. Cela peut signifier qu'elle doit être testée sur différentes configurations matérielles/logicielles ou même que les étapes à reproduire ne sont pas certaines.

  • 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 : problèmes qui ont un impact direct sur les performances du moteur ou de l'éditeur. Peut également être utilisé pour les demandes de pull qui améliorent les performances ou ajoutent des options conviviales pour le bas de gamme. Ne devrait pas être couplé avec Usability.

  • Régression : le bug est apparu après la publication d'une version stable ne présentant pas de 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 utilisé pour suivre d'autres problèmes (comme tous les problèmes liés au système de plugin).

  • Utilisabilité : questions qui ont un impact direct sur la convivialité pour l'utilisateur. Ne devrait pas être couplé avec 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: relates to the Animation system, editors and importers.

  • Assetlib : concerne les questions relatives à la bibliothèque d'asset.

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

  • Buildsystem : concerne les problèmes de compilation, soit liés au système de compilation SCons, soit aux particularités du compilateur.

  • Codestyle : concerne le style de programmation utilisé dans la base de code.

  • Core: anything related to the core engine. Specific topics are split off separately as they crop up.

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

  • Editor : concerne les issues de l'éditeur (principalement l'interface utilisateur).

  • Export: relates to the export system and templates.

  • GDExtension: relates to the GDExtension system for native extensions.

  • GDScript : se rapporte au GDScript.

  • GUI: relates to GUI (Control) nodes or to Nodes that compose user interfaces.

  • Import : concerne le système d'importation des ressources.

  • Input: relates to the input system.

  • I18n: relates to internationalization.

  • Multiplayer: relates to multiplayer (high-level networking) systems.

  • Navigation : concerne le système de navigation (comme A* et les navmesh).

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

  • Particules : particules, systèmes de particules et leurs éditeurs.

  • Physics : concerne le moteur physique (2D/3D).

  • Plugin : concerne les problèmes rencontrés lors de l'écriture de plugins.

  • Porting : concerne certaines plateformes spécifiques ou projets d'exportation.

  • Rendering : concerne les moteurs de rendu 2D et 3D.

  • Shaders : concerne le langage de shader de Godot, ou les shaders visuels.

  • Tests : concerne les tests unitaires.

  • Thirdparty : concerne les bibliothèques tiers dans Godot.

  • XR : concerne la Réalité Augmentée (AR) ou la Réalité Virtuelle (VR).

Les Issues ne correspondent généralement qu'à un seul sujet, bien qu'il ne soit pas impensable d'en voir qui puissent concerner deux sujets. L'idée est qu'il y aura des équipes de contributeurs spécialisés derrière tous les sujets, afin qu'ils puissent se concentrer sur les questions étiquetées avec le sujet de leur équipe.

Platforms:

Android, iOS, LinuxBSD, macOS, Web, Windows

Par défaut, on suppose qu'une issue donnée s'applique à toutes les plateformes. Si l'une des étiquettes de plate-forme est utilisée, elle est alors exclusive et l'hypothèse précédente ne tient plus (donc si c'est un bug sur par exemple Android et Linux exclusivement, sélectionnez ces deux plates-formes).

Labels de documentation

In the documentation repository, we use the following labels:

  • Archived : soit un doublon d'un autre problème, soit n'est pas valable. Une telle issue serait également fermé.

  • Bug : Information incorrecte dans une page existante. Ne doit pas être utilisé pour les informations manquantes.

  • Cherrypick : décris quelque chose qui peut être repris de la branche master (principale) pour être intégrée dans la branche stable actuelle.

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

  • Discussion : la question n'est pas consensuelle et nécessite une discussion plus approfondie afin de définir ce qui doit être fait exactement pour traiter le sujet.

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

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

  • Needs work : la pull request nécessite un travail supplémentaire avant de pouvoir être fusionnée.

  • Python: Pull requests that update Python code.

  • Salvageable : la pull request ne peut pas être fusionnée en raison de problèmes de conception ou de conflits de fusion et son auteur n'est plus actif. Cependant, elle peut toujours être reprise par un contributeur externe pour la rendre fusionnable. Pour ce faire, vous devez ouvrir une nouvelle demande de pull request basée sur la demande originale.

  • Tracker : issue utilisé pour suivre d'autres problèmes (comme tous les problèmes liés au système de plugin).

  • 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 : le problème concerne la référence de la classe, et non une page de documentation.

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

Étapes

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.