Merge pull request #2150 from symfony/docs-contributing

Adding an official format to be used for documentation pull requests

Author: weaverryan

CONTRIBUTING.md

@@ -2,4 +2,6 @@ Contributing
 ------------
 
 We love contributors! For more information on how you can contribute to the
-Symfony documentation, please read [Contributing to the Documentation](http://symfony.com/doc/current/contributing/documentation/overview.html) 
+Symfony documentation, please read [Contributing to the Documentation](http://symfony.com/doc/current/contributing/documentation/overview.html)
+and notice the [Pull Request Format](http://symfony.com/doc/current/contributing/documentation/overview.html#pull-request-format)
+that helps us merge your pull requests faster!

contributing/code/patches.rst

@@ -264,7 +264,7 @@ pull request message, like in:
     [Yaml] fixed something
     [Form] [Validator] [FrameworkBundle] added something
 
-The pull request description must include the following check list at the top
+The pull request description must include the following checklist at the top
 to ensure that contributions may be reviewed without needless feedback
 loops and that your contributions can be included into Symfony2 as quickly as
 possible:

contributing/documentation/overview.rst

@@ -46,8 +46,12 @@ Next, create a dedicated branch for your changes (for organization):
 
 You can now make your changes directly to this branch and commit them. When
 you're done, push this branch to *your* GitHub fork and initiate a pull request.
-The pull request will be between your ``improving_foo_and_bar`` branch and
-the ``symfony-docs`` ``master`` branch.
+
+Creating a Pull Request
+~~~~~~~~~~~~~~~~~~~~~~~
+
+Following the example, the pull request will default to be between your
+``improving_foo_and_bar`` branch and the ``symfony-docs`` ``master`` branch.
 
 .. image:: /images/docs-pull-request.png
    :align: center
@@ -60,8 +64,8 @@ the base branch to be 2.0 on the preview page:
 
 .. note::
 
-  All changes made to the 2.0 branch will be merged into 2.1 which in turn will be
-  merged into the master branch for the next release on a weekly basis.
+  All changes made to a branch (e.g. 2.0) will be merged up to each "newer"
+  branch (e.g. 2.1, master, etc) for the next release on a weekly basis.
 
 GitHub covers the topic of `pull requests`_ in detail.
 
@@ -70,6 +74,34 @@ GitHub covers the topic of `pull requests`_ in detail.
     The Symfony2 documentation is licensed under a Creative Commons
     Attribution-Share Alike 3.0 Unported :doc:`License <license>`.
 
+Pull Request Format
+~~~~~~~~~~~~~~~~~~~
+
+Unless you're fixing some minor typos, the pull request description must**
+include the following checklist to ensure that contributions may be reviewed
+without needless feedback loops and that your contributions can be included
+into the documentation as quickly as possible:
+
+.. code-block:: text
+
+    | Q             | A
+    | ------------- | ---
+    | Doc fix?      | [yes|no]
+    | New docs?     | [yes|no] (PR # on symfony/symfony if applicable)
+    | Applies to    | [Symfony version numbers this applies to]
+    | Fixed tickets | [comma separated list of tickets fixed by the PR]
+
+An example submission could now look as follows:
+
+.. code-block:: text
+
+    | Q             | A
+    | ------------- | ---
+    | Doc fix?      | yes
+    | New docs?     | yes (symfony/symfony#2500)
+    | Applies to    | all (or 2.1+)
+    | Fixed tickets | #1075
+
 .. tip::
 
     Please be patient. It can take from 15 minutes to several days for your changes