Merge pull request #41 from Ivorforce/pull-requests-section

Expand pull request subsection into its own section.

_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

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

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 <doc_pr_workflow>` 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 <https://github.com/godotengine/godot>`_. We generate

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

organization/pull_requests/index.rst

@@ -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

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 <doc_pr_workflow>`.
+Repeat this for other images and :ref:`make a Pull Request <doc_creating_pull_requests>`.

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

pull_requests/merge_guidelines.rst

@@ -1,4 +1,4 @@
-.. _doc_pr_review_guidelines:
+.. _doc_pr_merge_guidelines:
 
 Merge guidelines
 ================

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 <doc_pr_workflow>` that fixes a
-     specific problem (ideally closing a GitHub `issue <https://github.com/godotengine/godot>`_
-     or implementing a `proposal <https://github.com/godotengine/godot-proposals>`_).
+  1. A contributor reports an :ref:`issue <doc_reporting_issues>`
+     or proposes an :ref:`idea <doc_contributing_ideas>`.
 
-  2. The :ref:`bugsquad and triage team <doc_areas>` **categorize** the pull request,
+  2. A contributor :ref:`opens a pull request <doc_pr_workflow>` that addresses the issue
+     or implements the idea.
+
+  3. The :ref:`bugsquad and triage team <doc_areas>` **categorize** the pull request,
      adding appropriate tags and requesting reviews from :ref:`area maintainers <doc_areas>`.
 
-  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 <doc_areas>`, but reviews
      from other contributors help.
 

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.
 

pull_requests/review_guidelines.rst

@@ -1,7 +1,7 @@
 .. _doc_pr_review_guidelines:
 
-Review guidelines
-=================
+Reviewing pull requests
+=======================
 
 Code review and testing
 -----------------------

reporting_issues/first_steps.rst

@@ -1,3 +1,5 @@
+.. _doc_reporting_issues:
+
 Getting started
 ===============