bug symfony#3421 [Contributing] Cleaning the "contributing patch" page a bit (lemoinem)

weaverryan · weaverryan · commit f2f5e9ac94db · 2014-01-08T21:41:26.000-06:00
This PR was merged into the 2.4 branch. Discussion ---------- [Contributing] Cleaning the "contributing patch" page a bit | Q | A | ------------- | --- | Doc fix? | no | New docs? | no | Applies to | all | Fixed tickets | N/A I just mentioned the fact that `push -f` is required when rebasing and explicit that the "2.2 when bugfixing" is a follow up on the previous example (Not necessarily explicit at first). I also worked my way through the all document to replace wrong single back-tick occurrences by double backticks. Finally, I converted the mentions of PSR-1 and PSR-2 to links toward the respective PSR. PS: as per @wouterj request (symfony#3421 (comment)), I also replaced mentions of 2.2 by 2.3 Commits ------- c0de1cb [Contributing] Replace HEAD~3 by upstream/master 732758b [Contributing] Fix "When you finish" => "When you are finished" b25ec96 [Contributing] Replace mentions of 2.2 for 2.3 70ed645 [Contributing] Add PSR-1 and 2 links 6796ba8 [Contributing] Fix single vs double backtick issues b35e62b [Contributing] Clarify the rebase operation
diff --git a/contributing/code/patches.rst b/contributing/code/patches.rst
@@ -72,7 +72,7 @@ Get the Symfony2 source code:
 * Fork the `Symfony2 repository`_ (click on the "Fork" button);
 
 * After the "forking action" has completed, clone your fork locally
-  (this will create a `symfony` directory):
+  (this will create a ``symfony`` directory):
 
 .. code-block:: bash
 
@@ -105,16 +105,16 @@ Choose the right Branch
 ~~~~~~~~~~~~~~~~~~~~~~~
 
 Before working on a patch, you must determine on which branch you need to
-work. The branch should be based on the `master` branch if you want to add a
+work. The branch should be based on the ``master`` branch if you want to add a
 new feature. But if you want to fix a bug, use the oldest but still maintained
-version of Symfony where the bug happens (like `2.2`).
+version of Symfony where the bug happens (like ``2.3``).
 
 .. note::
 
     All bug fixes merged into maintenance branches are also merged into more
     recent branches on a regular basis. For instance, if you submit a patch
-    for the `2.2` branch, the patch will also be applied by the core team on
-    the `master` branch.
+    for the ``2.3`` branch, the patch will also be applied by the core team on
+    the ``master`` branch.
 
 Create a Topic Branch
 ~~~~~~~~~~~~~~~~~~~~~
@@ -126,26 +126,26 @@ topic branch:
 
     $ git checkout -b BRANCH_NAME master
 
-Or, if you want to provide a bugfix for the 2.2 branch, first track the remote
-`2.2` branch locally:
+Or, if you want to provide a bugfix for the ``2.3`` branch, first track the remote
+``2.3`` branch locally:
 
 .. code-block:: bash
 
-    $ git checkout -t origin/2.2
+    $ git checkout -t origin/2.3
 
-Then create a new branch off the 2.2 branch to work on the bugfix:
+Then create a new branch off the ``2.3`` branch to work on the bugfix:
 
 .. code-block:: bash
 
-    $ git checkout -b BRANCH_NAME 2.2
+    $ git checkout -b BRANCH_NAME 2.3
 
 .. tip::
 
-    Use a descriptive name for your branch (`ticket_XXX` where `XXX` is the
+    Use a descriptive name for your branch (``ticket_XXX`` where ``XXX`` is the
     ticket number is a good convention for bug fixes).
 
 The above checkout commands automatically switch the code to the newly created
-branch (check the branch you are working on with `git branch`).
+branch (check the branch you are working on with ``git branch``).
 
 Work on your Patch
 ~~~~~~~~~~~~~~~~~~
@@ -154,7 +154,7 @@ Work on the code as much as you want and commit as much as you want; but keep
 in mind the following:
 
 * Read about the Symfony :doc:`conventions <conventions>` and follow the
-  coding :doc:`standards <standards>` (use `git diff --check` to check for
+  coding :doc:`standards <standards>` (use ``git diff --check`` to check for
   trailing spaces -- also read the tip below);
 
 * Add unit tests to prove that the bug is fixed or that the new feature
@@ -164,7 +164,7 @@ in mind the following:
   provide a compatibility layer to support the old way) -- patches that break
   backward compatibility have less chance to be merged;
 
-* Do atomic and logically separate commits (use the power of `git rebase` to
+* Do atomic and logically separate commits (use the power of ``git rebase`` to
   have a clean and logical history);
 
 * Squash irrelevant commits that are just about fixing coding standards or
@@ -179,7 +179,7 @@ in mind the following:
 
     When submitting pull requests, `fabbot`_ checks your code
     for common typos and verifies that you are using the PHP coding standards
-    as defined in PSR-1 and PSR-2.
+    as defined in `PSR-1`_ and `PSR-2`_.
 
     A status is posted below the pull request description with a summary
     of any problems it detects or any Travis CI build failures.
@@ -199,11 +199,11 @@ Prepare your Patch for Submission
 When your patch is not about a bug fix (when you add a new feature or change
 an existing one for instance), it must also include the following:
 
-* An explanation of the changes in the relevant CHANGELOG file(s) (the ``[BC
-  BREAK]`` or the ``[DEPRECATION]`` prefix must be used when relevant);
+* An explanation of the changes in the relevant ``CHANGELOG`` file(s) (the
+ ``[BC BREAK]`` or the ``[DEPRECATION]`` prefix must be used when relevant);
 
 * An explanation on how to upgrade an existing application in the relevant
-  UPGRADE file(s) if the changes break backward compatibility or if you
+  ``UPGRADE`` file(s) if the changes break backward compatibility or if you
   deprecate something that will ultimately break backward compatibility.
 
 Step 3: Submit your Patch
@@ -228,7 +228,8 @@ while to finish your changes):
 
 .. tip::
 
-    Replace `master` with `2.2` if you are working on a bugfix
+    Replace ``master`` with the branch you selected previously (e.g. ``2.3``)
+    if you are working on a bugfix
 
 When doing the ``rebase`` command, you might have to fix merge conflicts.
 ``git status`` will show you the *unmerged* files. Resolve all the conflicts,
@@ -243,7 +244,7 @@ Check that all tests still pass and push your branch remotely:
 
 .. code-block:: bash
 
-    $ git push origin BRANCH_NAME
+    $ git push -f origin BRANCH_NAME
 
 Make a Pull Request
 ~~~~~~~~~~~~~~~~~~~
@@ -252,8 +253,8 @@ You can now make a pull request on the ``symfony/symfony`` Github repository.
 
 .. tip::
 
-    Take care to point your pull request towards ``symfony:2.2`` if you want
-    the core team to pull a bugfix based on the 2.2 branch.
+    Take care to point your pull request towards ``symfony:2.3`` if you want
+    the core team to pull a bugfix based on the ``2.3`` branch.
 
 To ease the core team work, always include the modified components in your
 pull request message, like in:
@@ -316,10 +317,10 @@ Some answers to the questions trigger some more requirements:
    documentation and reference it under the "Doc PR" section;
 
  * If you answer yes to "BC breaks?", the patch must contain updates to the
-   relevant CHANGELOG and UPGRADE files;
+   relevant ``CHANGELOG`` and ``UPGRADE`` files;
 
  * If you answer yes to "Deprecations?", the patch must contain updates to the
-   relevant CHANGELOG and UPGRADE files;
+   relevant ``CHANGELOG`` and ``UPGRADE`` files;
 
  * If you answer no to "Tests pass", you must add an item to a todo-list with
    the actions that must be done to fix the tests;
@@ -381,7 +382,7 @@ convert many commits to one commit. To do this, use the rebase command:
 
 .. code-block:: bash
 
-    $ git rebase -i HEAD~3
+    $ git rebase -i upstream/master
     $ git push -f origin BRANCH_NAME
 
 The number 3 here must equal the amount of commits in your branch. After you
@@ -393,11 +394,11 @@ type this command, an editor will popup showing a list of commits:
     pick 7fc64b4 second commit
     pick 7d33018 third commit
 
-To squash all commits into the first one, remove the word "pick" before the
-second and the last commits, and replace it by the word "squash" or just "s".
-When you save, Git will start rebasing, and if successful, will ask you to
-edit the commit message, which by default is a listing of the commit messages
-of all the commits. When you finish, execute the push command.
+To squash all commits into the first one, remove the word ``pick`` before the
+second and the last commits, and replace it by the word ``squash`` or just
+ ``s``. When you save, Git will start rebasing, and if successful, will ask
+ you to edit the commit message, which by default is a listing of the commit
+ messages of all the commits. When you are finished, execute the push command.
 
 .. _ProGit:                                http://git-scm.com/book
 .. _GitHub:                                https://github.com/signup/free
@@ -409,3 +410,5 @@ of all the commits. When you finish, execute the push command.
 .. _`travis-ci.org Getting Started Guide`: http://about.travis-ci.org/docs/user/getting-started/
 .. _`documentation repository`:            https://github.com/symfony/symfony-docs
 .. _`fabbot`:                              http://fabbot.io
+.. _`PSR-1`:                               http://www.php-fig.org/psr/psr-1/
+.. _`PSR-2`:                               http://www.php-fig.org/psr/psr-2/
