From 2d44c18a7653af2b4cb24fefa827a4c12fab2913 Mon Sep 17 00:00:00 2001 From: Lukas Tenbrink Date: Sun, 28 Dec 2025 10:09:03 +0100 Subject: [PATCH] Expand pull request subsection into its own section. Rename "review guidelines" to "Reviewing pull requests", to match other articles. Move "general rules and guidelines" to "Pull request guidelines", as it describes creating pull requests. --- _static/redirects.csv | 7 +++ documentation/class_reference.rst | 2 +- .../manual/contributing_to_the_manual.rst | 6 +-- index.rst | 15 ++++++- organization/pull_requests/index.rst | 18 -------- other/translations.rst | 2 +- .../creating_pull_requests.rst | 20 ++------- .../img/github_fork_button.png | Bin .../img/github_fork_make_pr.png | Bin .../img/github_fork_url.png | Bin .../testing_pull_requests_access_checks.webp | Bin .../img/testing_pull_requests_access_fork.png | Bin ...esting_pull_requests_checks_artifacts.webp | Bin ...g_pull_requests_checks_artifacts_list.webp | Bin ...g_pull_requests_command_line_checkout.webp | Bin .../img/testing_pull_requests_fork_zip.png | Bin .../testing_pull_requests_nightly_link.png | Bin .../merge_guidelines.rst | 2 +- .../pr_workflow.rst | 40 +++++++++++++----- .../pull_request_guidelines.rst | 4 +- .../review_guidelines.rst | 4 +- .../testing.rst | 0 reporting_issues/first_steps.rst | 2 + 23 files changed, 65 insertions(+), 57 deletions(-) delete mode 100644 organization/pull_requests/index.rst rename {organization/pull_requests => pull_requests}/creating_pull_requests.rst (96%) rename {organization/pull_requests => pull_requests}/img/github_fork_button.png (100%) rename {organization/pull_requests => pull_requests}/img/github_fork_make_pr.png (100%) rename {organization/pull_requests => pull_requests}/img/github_fork_url.png (100%) rename {organization/pull_requests => pull_requests}/img/testing_pull_requests_access_checks.webp (100%) rename {organization/pull_requests => pull_requests}/img/testing_pull_requests_access_fork.png (100%) rename {organization/pull_requests => pull_requests}/img/testing_pull_requests_checks_artifacts.webp (100%) rename {organization/pull_requests => pull_requests}/img/testing_pull_requests_checks_artifacts_list.webp (100%) rename {organization/pull_requests => pull_requests}/img/testing_pull_requests_command_line_checkout.webp (100%) rename {organization/pull_requests => pull_requests}/img/testing_pull_requests_fork_zip.png (100%) rename {organization/pull_requests => pull_requests}/img/testing_pull_requests_nightly_link.png (100%) rename {organization/pull_requests => pull_requests}/merge_guidelines.rst (99%) rename organization/pull_requests/review_process.rst => pull_requests/pr_workflow.rst (56%) rename organization/general_rules_and_guidelines.rst => pull_requests/pull_request_guidelines.rst (98%) rename {organization/pull_requests => pull_requests}/review_guidelines.rst (99%) rename {organization/pull_requests => pull_requests}/testing.rst (100%) diff --git a/_static/redirects.csv b/_static/redirects.csv index 1ea8e3f..cd4b3da 100644 --- a/_static/redirects.csv +++ b/_static/redirects.csv @@ -1,2 +1,9 @@ source,destination /documentation/translation/index.html,/other/translations.html +/organization/pull_requests/index.html,/pull_requests/pr_workflow.html +/organization/pull_requests/review_process.html,/pull_requests/pr_workflow.html +/organization/pull_requests/creating_pull_requests.html,/pull_requests/creating_pull_requests.html +/organization/general_rules_and_guidelines.html,/pull_requests/pull_request_guidelines.html +/organization/pull_requests/review_guidelines.html,/pull_requests/review_guidelines.html +/organization/pull_requests/testing.html,/pull_requests/testing.html +/organization/pull_requests/merge_guidelines.html,/pull_requests/merge_guidelines.html diff --git a/documentation/class_reference.rst b/documentation/class_reference.rst index 57fb33f..3937d8c 100644 --- a/documentation/class_reference.rst +++ b/documentation/class_reference.rst @@ -47,7 +47,7 @@ directory. To learn more about editing XML files refer to the latest documentati .. seealso:: For details on Git usage and the pull request workflow, please - refer to the :ref:`doc_pr_workflow` page. + refer to the :ref:`doc_creating_pull_requests` page. If you want to translate the class reference from English to another language, see :ref:`doc_editor_and_docs_localization`. This guide is diff --git a/documentation/manual/contributing_to_the_manual.rst b/documentation/manual/contributing_to_the_manual.rst index 1094d90..baf069d 100644 --- a/documentation/manual/contributing_to_the_manual.rst +++ b/documentation/manual/contributing_to_the_manual.rst @@ -20,9 +20,9 @@ files in the `godot-docs GitHub repository request triggers a rebuild of the online documentation upon merging. .. seealso:: For details on Git usage and the pull request workflow, please - refer to the :ref:`doc_pr_workflow` page. Most of what it describes - regarding the main godotengine/godot repository is also valid for - the docs repository. + refer to the :ref:`Pull requests ` section. + Most of what it describes regarding the main godotengine/godot + repository is also valid for the docs repository. .. warning:: The class reference's source files are in the `Godot engine repository `_. We generate diff --git a/index.rst b/index.rst index 411c287..fad728c 100644 --- a/index.rst +++ b/index.rst @@ -24,8 +24,6 @@ for your topic of interest. You can also use the search function in the top-left organization/how_to_contribute organization/areas - organization/pull_requests/index - organization/general_rules_and_guidelines organization/resources .. toctree:: @@ -49,6 +47,19 @@ for your topic of interest. You can also use the search function in the top-left triage/release_blockers triage/sprint_instructions +.. toctree:: + :hidden: + :maxdepth: 1 + :caption: Pull requests + :name: sec-pull-requests + + pull_requests/pr_workflow + pull_requests/pull_request_guidelines + pull_requests/creating_pull_requests + pull_requests/review_guidelines + pull_requests/testing + pull_requests/merge_guidelines + .. toctree:: :hidden: :maxdepth: 1 diff --git a/organization/pull_requests/index.rst b/organization/pull_requests/index.rst deleted file mode 100644 index 8dd8e4e..0000000 --- a/organization/pull_requests/index.rst +++ /dev/null @@ -1,18 +0,0 @@ -Pull requests -============= - -Pull requests are a fundamental building block in Godot's organization. -They are essentially requests to integrate specific code changes or updates into the project. -We use the same pull request workflow for the Godot engine, documentation, and other repositories. - -Learn how we work with pull requests in this section. - -.. toctree:: - :maxdepth: 1 - :name: sec-pull-requests - - creating_pull_requests - review_process - review_guidelines - testing - merge_guidelines diff --git a/other/translations.rst b/other/translations.rst index ee9f319..19c3efc 100644 --- a/other/translations.rst +++ b/other/translations.rst @@ -419,4 +419,4 @@ original image in the ``images`` subfolder and place your translated image there. In our example, the end result should be ``images/getting_started/step_by_step/img/project_manager_first_open.fr.png``. -Repeat this for other images and :ref:`make a Pull Request `. +Repeat this for other images and :ref:`make a Pull Request `. diff --git a/organization/pull_requests/creating_pull_requests.rst b/pull_requests/creating_pull_requests.rst similarity index 96% rename from organization/pull_requests/creating_pull_requests.rst rename to pull_requests/creating_pull_requests.rst index 07adba9..3c8821c 100644 --- a/organization/pull_requests/creating_pull_requests.rst +++ b/pull_requests/creating_pull_requests.rst @@ -1,26 +1,12 @@ -.. _doc_pr_workflow: +.. _doc_creating_pull_requests: Creating pull requests ====================== .. highlight:: shell -The so-called "PR workflow" used by Godot is common to many projects using -Git, and should be familiar to veteran free software contributors. The idea -is that only a small number (if any) commit directly to the *master* branch. -Instead, contributors *fork* the project (i.e. create a copy of it, which -they can modify as they wish), and then use the GitHub interface to request -a *pull* from one of their fork's branches to one branch of the original -(often named *upstream*) repository. - -The resulting *pull request* (PR) can then be reviewed by other contributors, -which might approve it, reject it, or most often request that modifications -be done. Once approved, the PR can then be merged by one of the core -developers, and its commit(s) will become part of the target branch (usually -the *master* branch). - -We will go together through an example to show the typical workflow and -associated Git commands. But first, let's have a quick look at the +We will go through an example together to show how to author a pull +request using Git commands. But first, let's have a quick look at the organization of Godot's Git repository. Git source repository diff --git a/organization/pull_requests/img/github_fork_button.png b/pull_requests/img/github_fork_button.png similarity index 100% rename from organization/pull_requests/img/github_fork_button.png rename to pull_requests/img/github_fork_button.png diff --git a/organization/pull_requests/img/github_fork_make_pr.png b/pull_requests/img/github_fork_make_pr.png similarity index 100% rename from organization/pull_requests/img/github_fork_make_pr.png rename to pull_requests/img/github_fork_make_pr.png diff --git a/organization/pull_requests/img/github_fork_url.png b/pull_requests/img/github_fork_url.png similarity index 100% rename from organization/pull_requests/img/github_fork_url.png rename to pull_requests/img/github_fork_url.png diff --git a/organization/pull_requests/img/testing_pull_requests_access_checks.webp b/pull_requests/img/testing_pull_requests_access_checks.webp similarity index 100% rename from organization/pull_requests/img/testing_pull_requests_access_checks.webp rename to pull_requests/img/testing_pull_requests_access_checks.webp diff --git a/organization/pull_requests/img/testing_pull_requests_access_fork.png b/pull_requests/img/testing_pull_requests_access_fork.png similarity index 100% rename from organization/pull_requests/img/testing_pull_requests_access_fork.png rename to pull_requests/img/testing_pull_requests_access_fork.png diff --git a/organization/pull_requests/img/testing_pull_requests_checks_artifacts.webp b/pull_requests/img/testing_pull_requests_checks_artifacts.webp similarity index 100% rename from organization/pull_requests/img/testing_pull_requests_checks_artifacts.webp rename to pull_requests/img/testing_pull_requests_checks_artifacts.webp diff --git a/organization/pull_requests/img/testing_pull_requests_checks_artifacts_list.webp b/pull_requests/img/testing_pull_requests_checks_artifacts_list.webp similarity index 100% rename from organization/pull_requests/img/testing_pull_requests_checks_artifacts_list.webp rename to pull_requests/img/testing_pull_requests_checks_artifacts_list.webp diff --git a/organization/pull_requests/img/testing_pull_requests_command_line_checkout.webp b/pull_requests/img/testing_pull_requests_command_line_checkout.webp similarity index 100% rename from organization/pull_requests/img/testing_pull_requests_command_line_checkout.webp rename to pull_requests/img/testing_pull_requests_command_line_checkout.webp diff --git a/organization/pull_requests/img/testing_pull_requests_fork_zip.png b/pull_requests/img/testing_pull_requests_fork_zip.png similarity index 100% rename from organization/pull_requests/img/testing_pull_requests_fork_zip.png rename to pull_requests/img/testing_pull_requests_fork_zip.png diff --git a/organization/pull_requests/img/testing_pull_requests_nightly_link.png b/pull_requests/img/testing_pull_requests_nightly_link.png similarity index 100% rename from organization/pull_requests/img/testing_pull_requests_nightly_link.png rename to pull_requests/img/testing_pull_requests_nightly_link.png diff --git a/organization/pull_requests/merge_guidelines.rst b/pull_requests/merge_guidelines.rst similarity index 99% rename from organization/pull_requests/merge_guidelines.rst rename to pull_requests/merge_guidelines.rst index 91b085f..4757ca2 100644 --- a/organization/pull_requests/merge_guidelines.rst +++ b/pull_requests/merge_guidelines.rst @@ -1,4 +1,4 @@ -.. _doc_pr_review_guidelines: +.. _doc_pr_merge_guidelines: Merge guidelines ================ diff --git a/organization/pull_requests/review_process.rst b/pull_requests/pr_workflow.rst similarity index 56% rename from organization/pull_requests/review_process.rst rename to pull_requests/pr_workflow.rst index 4d29838..8ae22e2 100644 --- a/organization/pull_requests/review_process.rst +++ b/pull_requests/pr_workflow.rst @@ -1,23 +1,43 @@ -Review and merge process -======================== +.. _doc_pr_workflow: -From a high level, the ideal life cycle of a pull request looks like the +Pull request workflow +===================== + +.. highlight:: shell + +The so-called "PR workflow" used by Godot is common to many projects using +Git, and should be familiar to veteran free software contributors. The idea +is that only a small number (if any) commit directly to the *master* branch. +Instead, contributors *fork* the project (i.e. create a copy of it, which +they can modify as they wish), and then use the GitHub interface to request +a *pull* from one of their fork's branches to one branch of the original +(often named *upstream*) repository. + +The resulting *pull request* (PR) can then be reviewed by other contributors, +who might approve it, reject it, or most often request that modifications +be done. Once approved, the PR can then be merged by one of the core +developers, and its commit(s) will become part of the target branch (usually +the *master* branch). + +From a high level, the ideal life cycle of a change to Godot looks like the following: - 1. A contributor :ref:`opens a pull request ` that fixes a - specific problem (ideally closing a GitHub `issue `_ - or implementing a `proposal `_). + 1. A contributor reports an :ref:`issue ` + or proposes an :ref:`idea `. - 2. The :ref:`bugsquad and triage team ` **categorize** the pull request, + 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, adding appropriate tags and requesting reviews from :ref:`area maintainers `. - 3. Contributors discuss **whether the approach of the PR is appropriate** to fix the problem + 4. Contributors discuss **whether the approach of the PR is appropriate** to fix the problem at hand, and leave feedback. - 4. Contributors **review the code**, and iterate improvements with the pull request author. + 5. Contributors **review the code**, and iterate improvements with the pull request author. When they are satisfied, they will approve the pull request. - 5. A release manager merges the pull request when there are sufficient approvals. A pull request + 6. A release manager merges the pull request when there are sufficient approvals. A pull request always needs approvals from the respective :ref:`area maintainers `, but reviews from other contributors help. diff --git a/organization/general_rules_and_guidelines.rst b/pull_requests/pull_request_guidelines.rst similarity index 98% rename from organization/general_rules_and_guidelines.rst rename to pull_requests/pull_request_guidelines.rst index 7a61ba9..4acc1c6 100644 --- a/organization/general_rules_and_guidelines.rst +++ b/pull_requests/pull_request_guidelines.rst @@ -1,5 +1,5 @@ -General rules and guidelines -============================ +Pull request guidelines +======================= This page contains guidelines relevant for contributing to any area of Godot. diff --git a/organization/pull_requests/review_guidelines.rst b/pull_requests/review_guidelines.rst similarity index 99% rename from organization/pull_requests/review_guidelines.rst rename to pull_requests/review_guidelines.rst index 5361953..86b3616 100644 --- a/organization/pull_requests/review_guidelines.rst +++ b/pull_requests/review_guidelines.rst @@ -1,7 +1,7 @@ .. _doc_pr_review_guidelines: -Review guidelines -================= +Reviewing pull requests +======================= Code review and testing ----------------------- diff --git a/organization/pull_requests/testing.rst b/pull_requests/testing.rst similarity index 100% rename from organization/pull_requests/testing.rst rename to pull_requests/testing.rst diff --git a/reporting_issues/first_steps.rst b/reporting_issues/first_steps.rst index d3e4baf..c605433 100644 --- a/reporting_issues/first_steps.rst +++ b/reporting_issues/first_steps.rst @@ -1,3 +1,5 @@ +.. _doc_reporting_issues: + Getting started ===============