Merge pull request #1378 from Calinou/improve-pr-workflow-page

Improve the PR workflow page

community/contributing/pr_workflow.rst

@@ -3,7 +3,7 @@
 Pull request workflow
 =====================
 
-.. highlight:: none
+.. 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
@@ -31,14 +31,14 @@ The `repository on GitHub <https://github.com/godotengine/godot>`_ is a
 issue tracker and PR system.
 
 .. note:: If you are contributing to the documention, its repository can
-          be found `here <https://github.com/godotengine/godot-docs>`_. 
+          be found `here <https://github.com/godotengine/godot-docs>`_.
 
 The Git version control system is the tool used to keep track of successive
 edits to the source code - to contribute efficiently to Godot, learning the
 basics of the Git command line is *highly* recommended. There exist some
 graphical interfaces for Git, but they usually encourage users to take bad
 habits regarding the Git and PR workflow, and we therefore recommend not to
-use them. In particular, we advise not to use Github's online editor for code 
+use them. In particular, we advise not to use GitHub's online editor for code
 contributions (although it's tolerated for small fixes or documentation changes)
 as it enforces one commit per file and per modification,
 which quickly leads to PRs with an unreadable Git history (especially after peer review).
@@ -50,20 +50,20 @@ which quickly leads to PRs with an unreadable Git history (especially after peer
 
 The branches on the Git repository are organized as follows:
 
--  The *master* branch is where the development of the next major version
+-  The ``master`` branch is where the development of the next major version
    occurs. As a development branch, it can be unstable
    and is not meant for use in production. This is where PRs should be done
    in priority.
--  The stable branches are named after their version, e.g. *3.0* and *2.1*.
-   They are used to backport bugfixes and enhancements from the *master*
+-  The stable branches are named after their version, e.g. ``3.0`` and ``2.1``.
+   They are used to backport bugfixes and enhancements from the ``master``
    branch to the currently maintained stable release (e.g. 3.0.2 or 2.1.5).
    As a rule of thumb, the last stable branch is maintained until the next
-   major version (e.g. the *2.0* branch was maintained until the release of
+   major version (e.g. the ``2.0`` branch was maintained until the release of
    Godot 2.1).
    If you want to make PRs against a maintained stable branch, you will have
-   to check if your changes are also relevant for the *master* branch.
+   to check if your changes are also relevant for the ``master`` branch.
 -  There might be feature branches at time, usually meant to be merged into
-   the *master* branch at some time.
+   the ``master`` branch at some time.
 
 Forking and cloning
 -------------------
@@ -82,10 +82,10 @@ Godot repo, with your GitHub username as namespace:
 
 You can then *clone* your fork, i.e. create a local copy of the online
 repository (in Git speak, the *origin remote*). If you haven't already,
-download Git from `its website <https://git-scm.com>`_ if you're using Windows or 
-Mac, if you're using Linux install it through your package manager. 
+download Git from `its website <https://git-scm.com>`_ if you're using Windows or
+macOS, or install it through your package manager if you're using Linux.
 
-.. note:: if you are on Windows open Git Bash to type commands. Mac and linux users
+.. note:: If you are on Windows, open Git Bash to type commands. macOS and Linux users
           can use their respective terminals.
 
 To clone your fork from GitHub, use the following command:
@@ -102,8 +102,8 @@ After a little while, you should have a ``godot`` directory in your current
 working directory. Move into it using the ``cd`` command:
 
 ::
-    
-    $ cd godot 
+
+    $ cd godot
 
 We will start by setting up a reference to the original repository that we forked:
 
@@ -112,10 +112,10 @@ We will start by setting up a reference to the original repository that we forke
     $ git remote add upstream https://github.com/godotengine/godot
     $ git fetch upstream
 
-This will create a reference named *upstream* pointing to the original
+This will create a reference named ``upstream`` pointing to the original
 godotengine/godot repository. This will be useful when you want to pull new
-commits from its *master* branch to update your fork. You have another
-*remote* reference named *origin*, which points to your fork.
+commits from its ``master`` branch to update your fork. You have another
+``remote`` reference named ``origin``, which points to your fork.
 
 You only need to do the above steps once, as long as you keep that local
 ``godot`` folder (which you can move around if you want, the relevant
@@ -139,26 +139,26 @@ file.
 Branching
 ---------
 
-By default, the ``git clone`` should have put you on the *master* branch of
-your fork (*origin*). To start your own feature development, we will create
+By default, the ``git clone`` should have put you on the ``master`` branch of
+your fork (``origin``). To start your own feature development, we will create
 a feature branch:
 
 ::
 
-    // Create the branch based on the current branch (master)
+    # Create the branch based on the current branch (master)
     $ git branch better-project-manager
 
-    // Change the current branch to the new one
+    # Change the current branch to the new one
     $ git checkout better-project-manager
 
 This command is equivalent:
 
 ::
 
-    // Change the current branch to a new named one, based on the current branch
+    # Change the current branch to a new named one, based on the current branch
     $ git checkout -b better-project-manager
 
-If you want to go back to the *master* branch, you'd use:
+If you want to go back to the ``master`` branch, you'd use:
 
 ::
 
@@ -177,14 +177,14 @@ command:
 Updating your branch
 --------------------
 
-This would not be needed the first time, just after you forked the upstream
-repository. However, the next time you want to work on something, you will
-notice that your fork's *master* is several commits behind the upstream
-*master* branch: pull requests from other contributors would have been merged
+This would not be needed the first time (just after you forked the upstream
+repository). However, the next time you want to work on something, you will
+notice that your fork's ``master`` is several commits behind the upstream
+``master`` branch: pull requests from other contributors would have been merged
 in the meantime.
 
 To ensure there won't be conflicts between the feature you develop and the
-current upstream *master* branch, you will have to update your branch by
+current upstream ``master`` branch, you will have to update your branch by
 *pulling* the upstream branch.
 
 ::
@@ -195,10 +195,10 @@ However, if you had local commits, this method will create a so-called "merge
 commit", and you will soon hear from fellow contributors that those are not
 wanted in PRs. Then how to update the branch without creating a merge commit?
 You will have to use the ``--rebase`` option, so that your local commits are
-replayed on top of the updated upstream *master* branch. It will effectively
+replayed on top of the updated upstream ``master`` branch. It will effectively
 modify the Git history of your branch, but that is for the greater good.
 
-Then command that you should (almost) always use is there:
+Therefore, the command that you should (almost) always use is:
 
 ::
 
@@ -214,7 +214,7 @@ You would then do your changes to our example's
 By default, those changes are *unstaged*. The staging area is a layer between
 your working directory (where you make your modifications) and the local git
 repository (the commits and all the metadata in the ``.git`` folder). To
-bring changes from the working directory to the git repository, you need to
+bring changes from the working directory to the Git repository, you need to
 *stage* them with the ``git add`` command, and then to commit them with the
 ``git commit`` command.
 
@@ -233,7 +233,7 @@ before staging it, while it is staged, and after it has been committed.
   modifications.
 - ``git commit`` will commit the staged files. It will open a text editor
   (you can define the one you want to use with the ``GIT_EDITOR`` environment
-  variable or the ``core.editor`` setting in your Git config) to let you
+  variable or the ``core.editor`` setting in your Git configuration) to let you
   write a commit log. You can use ``git commit -m "Cool commit log"`` to
   write the log directly.
 - ``git log`` will show you the last commits of your current branch. If you
@@ -248,36 +248,36 @@ Here's how the shell history could look like on our example:
 
 ::
 
-    // It's nice to know where you're starting from
+    # It's nice to know where you're starting from
     $ git log
 
-    // Do changes to the project manager with the nano text editor
+    # Do changes to the project manager with the nano text editor
     $ nano editor/project_manager.cpp
 
-    // Find an unrelated bug in Control and fix it
+    # Find an unrelated bug in Control and fix it
     $ nano scene/gui/control.cpp
 
-    // Review changes
+    # Review changes
     $ git status
     $ git diff
 
-    // We'll do two commits for our unrelated changes,
-    // starting by the Control changes necessary for the PM enhancements
+    # We'll do two commits for our unrelated changes,
+    # starting by the Control changes necessary for the PM enhancements
     $ git add scene/gui/control.cpp
     $ git commit -m "Fix handling of margins in Control"
 
-    // Check we did good
+    # Check we did good
     $ git log
     $ git show
     $ git status
 
-    // Make our second commit
+    # Make our second commit
     $ git add editor/project_manager.cpp
     $ git commit -m "Add a pretty banner to the project manager"
     $ git log
 
-With this, we should have two new commits in our *better-project-manager*
-branch which were not in the *master* branch. They are still only local
+With this, we should have two new commits in our ``better-project-manager``
+branch which were not in the ``master`` branch. They are still only local
 though, the remote fork does not know about them, nor does the upstream repo.
 
 Pushing changes to a remote
@@ -308,9 +308,9 @@ Issuing a pull request
 ----------------------
 
 When you load your fork's branch on GitHub, you should see a line saying
-"This branch is 2 commits ahead of godotengine:master." (and potentially some
-commits behind, if your *master* branch was out of sync with the upstream
-*master* branch.
+*"This branch is 2 commits ahead of godotengine:master."* (and potentially some
+commits behind, if your ``master`` branch was out of sync with the upstream
+``master`` branch.
 
 .. image:: img/github_fork_make_pr.png
 
@@ -321,7 +321,7 @@ If not (e.g. it has way more commits, or says there are merge conflicts),
 don't create the PR, something went wrong. Go to IRC and ask for support :)
 
 Use an explicit title for the PR and put the necessary details in the comment
-area. You can drag and drop screenshots, gifs or zipped projects if relevant,
+area. You can drag and drop screenshots, GIFs or zipped projects if relevant,
 to showcase what your work implements. Click "Create a pull request", and
 tadaa!
 
@@ -338,10 +338,10 @@ branch, push it to your fork, and the PR will be updated automatically:
 
 ::
 
-    // Check out your branch again if you had changed in the meantime
+    # Check out your branch again if you had changed in the meantime
     $ git checkout better-project-manager
 
-    // Fix a mistake
+    # Fix a mistake
     $ nano editor/project_manager.cpp
     $ git add editor/project_manager.cpp
     $ git commit -m "Fix a typo in the banner's title"
@@ -374,7 +374,7 @@ do:
 
 ::
 
-    // The HEAD~X syntax means X commits before HEAD
+    # The HEAD~X syntax means X commits before HEAD
     $ git rebase -i HEAD~2
 
 This will open a text editor with:
@@ -404,7 +404,7 @@ commits.
 
 .. note:: You could have avoided this rebase by using ``git commit --amend``
           when fixing the typo. This command will write the staged changes
-          directly into the *last* commit (*HEAD*), instead of creating a new
+          directly into the *last* commit (``HEAD``), instead of creating a new
           commit like we did in this example. So it is equivalent to what we
           did with a new commit and then a rebase to mark it as "fixup".
 
@@ -434,22 +434,22 @@ And tadaa! Git will happily *replace* your remote branch with what you had
 locally (so make sure that's what you wanted, using ``git log``). This will
 also update the PR accordingly.
 
-Deleting a Git Branch
+Deleting a Git branch
 ---------------------
 
-After your pull request gets merged there's one last thing you should do, delete your 
-Git branch for the PR. There wont be issues if you don't delete your branch, but it's 
-good practice to do so. You'll need to do this twice, once for the local branch and another 
+After your pull request gets merged, there's one last thing you should do: delete your
+Git branch for the PR. There won't be issues if you don't delete your branch, but it's
+good practice to do so. You'll need to do this twice, once for the local branch and another
 for the remote branch on GitHub.
 
-To delete our better project manager branch locally use this command:
+To delete our better project manager branch locally, use this command:
 
 ::
 
-    $ git branch -d better-project-manager 
+    $ git branch -d better-project-manager
 
-Alternatively, if the branch hadn't been merged yet and we wanted to delete it anyway, instead 
-of ``-d`` you would use ``-D``. 
+Alternatively, if the branch hadn't been merged yet and we wanted to delete it anyway, instead
+of ``-d`` you would use ``-D``.
 
 Next, to delete the remote branch on GitHub use this command: