From b35e62b28e32760f9d90128ec8a3fd78f6c8fb47 Mon Sep 17 00:00:00 2001 From: Mathieu Lemoine Date: Sat, 4 Jan 2014 12:25:32 -0500 Subject: [PATCH 1/6] [Contributing] Clarify the rebase operation I just mentioned the fact that `push -f` is usually required when rebasing and explicit that the "2.2 when bugfixing" is a follow up on the previous example (Not necessarily explicit at first). --- contributing/code/patches.rst | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/contributing/code/patches.rst b/contributing/code/patches.rst index d2dae74d2fd..cf262b0faa7 100644 --- a/contributing/code/patches.rst +++ b/contributing/code/patches.rst @@ -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.2``) + 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 ~~~~~~~~~~~~~~~~~~~ From 6796ba87cc48f5fe2bf940e93c5b8562d54fdae8 Mon Sep 17 00:00:00 2001 From: Mathieu Lemoine Date: Sat, 4 Jan 2014 13:33:59 -0500 Subject: [PATCH 2/6] [Contributing] Fix single vs double backtick issues --- contributing/code/patches.rst | 46 +++++++++++++++++------------------ 1 file changed, 23 insertions(+), 23 deletions(-) diff --git a/contributing/code/patches.rst b/contributing/code/patches.rst index cf262b0faa7..f4a1c28fde5 100644 --- 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.2``). .. 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.2`` branch, the patch will also be applied by the core team on + the ``master`` branch. Create a Topic Branch ~~~~~~~~~~~~~~~~~~~~~ @@ -126,14 +126,14 @@ 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.2`` branch, first track the remote +``2.2`` branch locally: .. code-block:: bash $ git checkout -t origin/2.2 -Then create a new branch off the 2.2 branch to work on the bugfix: +Then create a new branch off the ``2.2`` branch to work on the bugfix: .. code-block:: bash @@ -141,11 +141,11 @@ Then create a new branch off the 2.2 branch to work on the bugfix: .. 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 ` and follow the - coding :doc:`standards ` (use `git diff --check` to check for + coding :doc:`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 @@ -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 @@ -254,7 +254,7 @@ 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. + the core team to pull a bugfix based on the ``2.2`` branch. To ease the core team work, always include the modified components in your pull request message, like in: @@ -317,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; @@ -394,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 finish, execute the push command. .. _ProGit: http://git-scm.com/book .. _GitHub: https://github.com/signup/free From 70ed645240cfd7e76d09ce0eb16309856c92a7e0 Mon Sep 17 00:00:00 2001 From: Mathieu Lemoine Date: Sat, 4 Jan 2014 13:34:34 -0500 Subject: [PATCH 3/6] [Contributing] Add PSR-1 and 2 links --- contributing/code/patches.rst | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/contributing/code/patches.rst b/contributing/code/patches.rst index f4a1c28fde5..c6ec35864d1 100644 --- a/contributing/code/patches.rst +++ b/contributing/code/patches.rst @@ -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. @@ -410,3 +410,5 @@ second and the last commits, and replace it by the word ``squash`` or just .. _`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/ From b25ec96eb822a03c466c828dc9838f9a8f766ae5 Mon Sep 17 00:00:00 2001 From: Mathieu Lemoine Date: Sat, 4 Jan 2014 13:35:44 -0500 Subject: [PATCH 4/6] [Contributing] Replace mentions of 2.2 for 2.3 As per WouterJ request: https://github.com/symfony/symfony-docs/pull/3421#issuecomment-31585092 --- contributing/code/patches.rst | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/contributing/code/patches.rst b/contributing/code/patches.rst index c6ec35864d1..2f313f87f69 100644 --- a/contributing/code/patches.rst +++ b/contributing/code/patches.rst @@ -107,13 +107,13 @@ 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 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 + for the ``2.3`` branch, the patch will also be applied by the core team on the ``master`` branch. Create a Topic Branch @@ -126,18 +126,18 @@ 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:: @@ -228,7 +228,7 @@ while to finish your changes): .. tip:: - Replace ``master`` with the branch you selected previously (e.g. ``2.2``) + 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. @@ -253,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: From 732758b850438ed12ab53a84858fb2826423a17b Mon Sep 17 00:00:00 2001 From: Mathieu Lemoine Date: Mon, 6 Jan 2014 08:10:45 -0500 Subject: [PATCH 5/6] [Contributing] Fix "When you finish" => "When you are finished" As per @xabbuh suggestion: https://github.com/symfony/symfony-docs/pull/3421#discussion_r8661716 --- contributing/code/patches.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/contributing/code/patches.rst b/contributing/code/patches.rst index 2f313f87f69..0e38190bb33 100644 --- a/contributing/code/patches.rst +++ b/contributing/code/patches.rst @@ -398,7 +398,7 @@ 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. + 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 From c0de1cb392b45fad07978122126fd4ab9ad60bac Mon Sep 17 00:00:00 2001 From: Mathieu Lemoine Date: Mon, 6 Jan 2014 14:26:47 -0500 Subject: [PATCH 6/6] [Contributing] Replace HEAD~3 by upstream/master As per @cordoval suggestion: https://github.com/symfony/symfony-docs/pull/3421#discussion_r8670868 --- contributing/code/patches.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/contributing/code/patches.rst b/contributing/code/patches.rst index 0e38190bb33..7f0667ea960 100644 --- a/contributing/code/patches.rst +++ b/contributing/code/patches.rst @@ -382,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