Permalink
Browse files

minor #4245 [Contributing] tweaks to the contribution chapter (xabbuh)

This PR was merged into the 2.3 branch.

Discussion
----------

[Contributing] tweaks to the contribution chapter

| Q             | A
| ------------- | ---
| Doc fix?      | yes
| New docs?     | no
| Applies to    | all
| Fixed tickets |

Some tweaks for the changes made in #4223.

@javiereguiluz Sorry,  didn't find the time to review it in the first run.

Commits
-------

f4b0b8e tweaks to the contribution chapter
  • Loading branch information...
weaverryan committed Oct 2, 2014
2 parents c2342a7 + f4b0b8e commit 990b4531f8ee636e3167537bd0dce7c88da16b98
Showing with 21 additions and 25 deletions.
  1. +5 −14 contributing/documentation/format.rst
  2. +16 −11 contributing/documentation/overview.rst
@@ -33,24 +33,15 @@ 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
.. code-block:: yaml
{ foo: bar, bar: { foo: bar, bar: baz } }
If your PHP code begins with ``<?php``, then you need to use ``html+php`` as
the name of the highlighted syntax:
.. code-block:: rst
.. code-block:: html+php
<?php echo $this->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
~~~~~~~~~~~~~~~~~~~~~
@@ -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.

0 comments on commit 990b453

Please sign in to comment.