diff --git a/contributing/documentation/format.rst b/contributing/documentation/format.rst index 4f464e85001..6b89158101b 100644 --- a/contributing/documentation/format.rst +++ b/contributing/documentation/format.rst @@ -33,8 +33,8 @@ roles to the standard reST markup. Read more about the `Sphinx Markup Constructs Syntax Highlighting ~~~~~~~~~~~~~~~~~~~ -PHP is the default syntax highlight applied to all code blocks. You can change -it with the ``code-block`` directive: +PHP is the default syntax highlighter applied to all code blocks. You can +change it with the ``code-block`` directive: .. code-block:: rst @@ -42,15 +42,6 @@ it with the ``code-block`` directive: { foo: bar, bar: { foo: bar, bar: baz } } -If your PHP code begins with ``foobar(); ?> - .. note:: Besides all of the major programming languages, the syntax highlighter @@ -183,7 +174,7 @@ If you're documenting a brand new feature or a change that's been made in Symfony, you should precede your description of the change with a ``.. versionadded:: 2.X`` directive and a short description: -.. code-block:: text +.. code-block:: rst .. versionadded:: 2.3 The ``askHiddenResponse`` method was introduced in Symfony 2.3. @@ -193,7 +184,7 @@ Symfony, you should precede your description of the change with a If you're documenting a behavior change, it may be helpful to *briefly* describe how the behavior has changed. -.. code-block:: text +.. code-block:: rst .. versionadded:: 2.3 The ``include()`` function is a new Twig feature that's available in @@ -204,7 +195,7 @@ a new branch of the documentation is created from the ``master`` branch. At this point, all the ``versionadded`` tags for Symfony versions that have reached end-of-life will be removed. For example, if Symfony 2.5 were released today, and 2.2 had recently reached its end-of-life, the 2.2 ``versionadded`` -tags would be removed from the new 2.5 branch. +tags would be removed from the new ``2.5`` branch. Testing Documentation ~~~~~~~~~~~~~~~~~~~~~ diff --git a/contributing/documentation/overview.rst b/contributing/documentation/overview.rst index c50c29be5f2..1ad45ef7b4f 100644 --- a/contributing/documentation/overview.rst +++ b/contributing/documentation/overview.rst @@ -3,10 +3,10 @@ Contributing to the Documentation One of the essential principles of the Symfony project is that **documentation is as important as code**. That's why a great amount of resources are dedicated to -documenting new features and to keeping the rest of the documentation up to date. +documenting new features and to keeping the rest of the documentation up-to-date. -More than 800 developers all around the world have contributed to Symfony's -documentation, and we are glad that you are considering joining this big family. +More than 700 developers all around the world have contributed to Symfony's +documentation and we are glad that you are considering joining this big family. This guide will explain everything you need to contribute to the Symfony documentation. @@ -27,9 +27,9 @@ Before Your First Contribution Your First Documentation Contribution ------------------------------------- -In this section you'll learn how to contribute to the Symfony documentation for +In this section, you'll learn how to contribute to the Symfony documentation for the first time. The next section will explain the shorter process you'll follow -in the future for every contribution after your first. +in the future for every contribution after your first one. Let's imagine that you want to improve the installation chapter of the Symfony book. In order to make your changes, follow these steps: @@ -164,8 +164,12 @@ Now you can **sync your fork** by executing the following command: $ cd projects/symfony-docs/ $ git fetch upstream - $ git checkout master - $ git merge upstream/master + $ git checkout 2.3 + $ git merge upstream/2.3 + +This command will update the ``2.3`` branch, which is the one you used to +create the new branch for your changes. If have used another base branch, +e.g. ``master``, replace the ``2.3`` with the appropriate branch name. Great! Now you can proceed by following the same steps explained in the previous section: @@ -212,8 +216,8 @@ steps to contribute to the Symfony documentation, which you can use as a # sync your fork with the official Symfony repository $ cd projects/symfony-docs/ $ git fetch upstream - $ git checkout master - $ git merge upstream/master + $ git checkout 2.3 + $ git merge upstream/2.3 # create a new branch from the oldest maintained version $ git checkout 2.3 @@ -262,10 +266,11 @@ Why Should I Use the Oldest Maintained Branch Instead of the Master Branch? Consistent with Symfony's source code, the documentation repository is split into multiple branches, corresponding to the different versions of Symfony itself. -The master branch holds the documentation for the development branch of the code. +The ``master`` branch holds the documentation for the development branch of +the code. Unless you're documenting a feature that was introduced after Symfony 2.3, -your changes should always be based on the 2.3 branch. Documentation managers +your changes should always be based on the ``2.3`` branch. Documentation managers will use the necessary Git-magic to also apply your changes to all the active branches of the documentation.