Skip to content

Commit

Permalink
bug #3421 [Contributing] Cleaning the "contributing patch" page a bit…
Browse files Browse the repository at this point in the history 
… (lemoinem)

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 (#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
  • Loading branch information
@weaverryan
weaverryan committed Jan 9, 2014
2 parents f08e2a5 + c0de1cb commit f2f5e9a
Showing 1 changed file with 33 additions and 30 deletions.
63 changes: 33 additions & 30 deletions contributing/code/patches.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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
~~~~~~~~~~~~~~~~~~~~~
Expand All @@ -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
~~~~~~~~~~~~~~~~~~
Expand All @@ -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
Expand All @@ -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
Expand All @@ -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.
Expand All @@ -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
Expand All @@ -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,
Expand All @@ -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
~~~~~~~~~~~~~~~~~~~
Expand All @@ -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:
Expand Down Expand Up @@ -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;
Expand Down Expand Up @@ -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
Expand All @@ -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
Expand All @@ -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/

0 comments on commit f2f5e9a

Please sign in to comment.