Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[Contributing] Cleaning the "contributing patch" page a bit #3421

Merged
merged 6 commits into from
Jan 9, 2014
Merged

[Contributing] Cleaning the "contributing patch" page a bit #3421

Changes from 5 commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
b35e62b
[Contributing] Clarify the rebase operation
lemoinem Jan 4, 2014
6796ba8
[Contributing] Fix single vs double backtick issues
lemoinem Jan 4, 2014
70ed645
[Contributing] Add PSR-1 and 2 links
lemoinem Jan 4, 2014
b25ec96
[Contributing] Replace mentions of 2.2 for 2.3
lemoinem Jan 4, 2014
732758b
[Contributing] Fix "When you finish" => "When you are finished"
lemoinem Jan 6, 2014
c0de1cb
[Contributing] Replace HEAD~3 by upstream/master
lemoinem Jan 6, 2014
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
61 changes: 32 additions & 29 deletions contributing/code/patches.rst
View file
Open in desktop
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
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

i wonder if we can change the rebase -i HEAD~3 for a git rebase -i origin/2.3 or origin/master, that is what we use in Gush

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

where in this article do we use rebase -i HEAD~3?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

https://github.com/lemoinem/symfony-docs/blob/732758b850438ed12ab53a84858fb2826423a17b/contributing/code/patches.rst#rework-your-patch

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

There you go ! 😄


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