From a9dd0b9f4ab679f22539c2095c9ee4fcd0d2f38d Mon Sep 17 00:00:00 2001 From: Lukas Tenbrink Date: Wed, 28 Jan 2026 15:18:06 +0100 Subject: [PATCH] Add a custom role for team links, to simplify styling and linking them. --- _extensions/{area_table.py => godot_areas.py} | 35 +++++++++++++++++++ conf.py | 2 +- .../guidelines/content_guidelines.rst | 4 +-- organization/areas.rst | 4 +++ organization/how_to_contribute.rst | 2 +- other/triage/guidelines.rst | 4 +-- other/triage/index.rst | 2 +- pull_requests/pr_workflow.rst | 4 +-- 8 files changed, 48 insertions(+), 9 deletions(-) rename _extensions/{area_table.py => godot_areas.py} (76%) diff --git a/_extensions/area_table.py b/_extensions/godot_areas.py similarity index 76% rename from _extensions/area_table.py rename to _extensions/godot_areas.py index 9019221..61786e9 100644 --- a/_extensions/area_table.py +++ b/_extensions/godot_areas.py @@ -1,9 +1,11 @@ """ A directive for organization/areas.rst to render the area tables. """ +import dataclasses from docutils import nodes from docutils.parsers.rst import Directive +from sphinx.roles import XRefRole import re area_table_rows = ("Communication", "GitHub reviews", "GitHub labels", "Triage project", "Maintainers") @@ -88,5 +90,38 @@ class TableDirective(Directive): return [table] +class TeamRole(XRefRole): + def __init__(self): + self.is_patched: bool = False + self.title: str = "" + self.role: str = "" + + super().__init__() + + def run(self) -> tuple[list[nodes.Node], list[nodes.system_message]]: + # Hacky, but apparently easiest way to get normal link behavior. + if not self.is_patched: + role = self.target.lower().replace(" ", "_") + + if self.has_explicit_title: + self.title = f"◆ {self.title}" + else: + title = f"◆ {self.title} team" + + self.target = f"team_{role}" + self.has_explicit_title = True + + self.is_patched = True + + self.refdomain, self.reftype = "std", "ref" + self.classes = ['xref', self.reftype] + + if self.disabled: + return self.create_non_xref_node() + else: + return self.create_xref_node() + + def setup(app): app.add_directive('gdareatable', TableDirective) + app.add_role('team', TeamRole()) diff --git a/conf.py b/conf.py index b940fb8..d96970d 100644 --- a/conf.py +++ b/conf.py @@ -21,7 +21,7 @@ extensions = [ "sphinxext.opengraph", "sphinx_copybutton", "sphinxcontrib.video", - "area_table", + "godot_areas", "gdscript", ] diff --git a/documentation/guidelines/content_guidelines.rst b/documentation/guidelines/content_guidelines.rst index 52807e2..02ce95d 100644 --- a/documentation/guidelines/content_guidelines.rst +++ b/documentation/guidelines/content_guidelines.rst @@ -31,7 +31,7 @@ should ensure that we cover everything Godot does. .. note:: - When adding or updating an engine feature, the documentation team needs to + When adding or updating an engine feature, the :team:`Documentation` needs to know about it. Contributors should open an issue on the `godot-docs` repository when their work gets merged and requires documentation. @@ -72,7 +72,7 @@ could be considered part of the official API. This means that documenting uninte rely on things that might need to be changed in the future, limiting what we can change without breaking compatibility. To avoid accidentally documenting unintended behavior, :ref:`area maintainers ` should always review -changes to the documentation of their respective area. The documentation team should help organizing this and with +changes to the documentation of their respective area. The :team:`Documentation` should help organizing this and with writing when needed. These rules are not absolute, but are usually correct. If you are unsure what to document, don't hesitate to ask the diff --git a/organization/areas.rst b/organization/areas.rst index 97ce890..f08a260 100644 --- a/organization/areas.rst +++ b/organization/areas.rst @@ -124,6 +124,8 @@ Demos :github_reviews: @godotengine/demos :maintainers: Aaron Franke (@aaronfranke), Ilaria Cislaghi (@QbieShay), K. S. Ernest Lee (@fire), Rémi Verschelde (@akien-mga) +.. _team_documentation: + Documentation ------------- @@ -287,6 +289,8 @@ for their area. :github_labels: topic:tests :maintainers: Hugo Locurcio (@Calinou), Gordon MacPherson (@RevoluPowered), Hendrik Brucker (@Geometror), Rémi Verschelde (@akien-mga) +.. _team_triage: + Bugsquad / Issue triage ~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/organization/how_to_contribute.rst b/organization/how_to_contribute.rst index 7e6cab8..7b7f8ae 100644 --- a/organization/how_to_contribute.rst +++ b/organization/how_to_contribute.rst @@ -87,7 +87,7 @@ Participate in Godot's development `Weblate `__. - **Bugsquad & triage** - With so many bug reports and pull requests being opened each day, the triage team — also called bugsquad — is + With so many bug reports and pull requests being opened each day, the :team:`Triage` — also called bugsquad — is invaluable to keep things organized. If you'd like to get involved, please visit :ref:`doc_bug_triage_intro`! diff --git a/other/triage/guidelines.rst b/other/triage/guidelines.rst index cdbd0a8..9342c74 100644 --- a/other/triage/guidelines.rst +++ b/other/triage/guidelines.rst @@ -3,11 +3,11 @@ Bug triage guidelines ===================== -This page describes the typical workflow of the bug triage team aka +This page describes the typical workflow of the :team:`Triage` 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. +hesitate to propose modifications to the following guidelines Issues management ----------------- diff --git a/other/triage/index.rst b/other/triage/index.rst index 70a9ba1..670d69f 100644 --- a/other/triage/index.rst +++ b/other/triage/index.rst @@ -1,7 +1,7 @@ Bugsquad and triage =================== -This section explains the workflow and guidelines of the :ref:`triage team `. +This section explains the workflow and guidelines of the :team:`Triage`. .. toctree:: :maxdepth: 1 diff --git a/pull_requests/pr_workflow.rst b/pull_requests/pr_workflow.rst index 2fe4ca4..a2ed593 100644 --- a/pull_requests/pr_workflow.rst +++ b/pull_requests/pr_workflow.rst @@ -28,7 +28,7 @@ following: 2. A contributor :ref:`opens a pull request ` that addresses the issue or implements the idea. - 3. The :ref:`bugsquad and triage team ` **categorize** the pull request, + 3. The :team:`Bugsquad and triage team ` **categorize** the pull request, adding appropriate tags and requesting reviews from :ref:`area maintainers `. 4. Contributors discuss **whether the approach of the PR is appropriate** to fix the problem @@ -52,7 +52,7 @@ this before they became maintainers. When will a pull request get reviewed? -------------------------------------- -When you open a new pull request, :ref:`Area maintainers ` are notified immediately. +When you open a new pull request, :ref:`area maintainers ` are notified immediately. However, a lot of pull requests are opened every day, so reviews can take a while to come in. Going by historical data, you can expect the following review timelines: