diff --git a/contributing/documentation/format.rst b/contributing/documentation/format.rst index 491d27df407..4f464e85001 100644 --- a/contributing/documentation/format.rst +++ b/contributing/documentation/format.rst @@ -1,17 +1,19 @@ Documentation Format ==================== -The Symfony2 documentation uses `reStructuredText`_ as its markup language and -`Sphinx`_ for building the output (HTML, PDF, ...). +The Symfony documentation uses reStructuredText_ as its markup language and +Sphinx_ for generating the documentation in the formats read by the end users, +such as HTML and PDF. reStructuredText ---------------- -reStructuredText *"is an easy-to-read, what-you-see-is-what-you-get plaintext -markup syntax and parser system"*. +reStructuredText is a plaintext markup syntax similar to Markdown, but much +stricter with its syntax. If you are new to reStructuredText, take some time to +familiarize with this format by reading the existing `Symfony documentation`_ -You can learn more about its syntax by reading existing Symfony2 `documents`_ -or by reading the `reStructuredText Primer`_ on the Sphinx website. +If you want to learn more about this format, check out the `reStructuredText Primer`_ +tutorial and the `reStructuredText Reference`_. .. caution:: @@ -24,14 +26,14 @@ or by reading the `reStructuredText Primer`_ on the Sphinx website. Sphinx ------ -Sphinx is a build system that adds some nice tools to create documentation -from reStructuredText documents. As such, it adds new directives and -interpreted text roles to the standard reST `markup`_. +Sphinx is a build system that provides tools to create documentation from +reStructuredText documents. As such, it adds new directives and interpreted text +roles to the standard reST markup. Read more about the `Sphinx Markup Constructs`_. Syntax Highlighting ~~~~~~~~~~~~~~~~~~~ -All code examples uses PHP as the default highlighted language. You can change +PHP is the default syntax highlight applied to all code blocks. You can change it with the ``code-block`` directive: .. code-block:: rst @@ -41,7 +43,7 @@ it with the ``code-block`` directive: { foo: bar, bar: { foo: bar, bar: baz } } If your PHP code begins with ``` -You can also add links to the API documentation: +.. note:: + + Although they are technically correct, avoid the use of relative internal + links such as the following, because they break the references in the + generated PDF documentation: + + .. code-block:: rst + + :doc:`controller` + + :doc:`event_dispatcher/introduction` + + :doc:`environments` + +**Links to the API** follow a different syntax, where you must specify the type +of the linked resource (``namespace``, ``class`` or ``method``): .. code-block:: rst @@ -148,7 +166,7 @@ You can also add links to the API documentation: :method:`Symfony\\Component\\HttpKernel\\Bundle\\Bundle::build` -and to the PHP documentation: +**Links to the PHP documentation** follow a pretty similar syntax: .. code-block:: rst @@ -158,20 +176,55 @@ and to the PHP documentation: :phpfunction:`iterator_to_array` -Testing Documentation -~~~~~~~~~~~~~~~~~~~~~ +New Features or Behavior Changes +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -To test documentation before a commit: +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: -* Install `Sphinx`_; -* Install the Sphinx extensions using git submodules: ``git submodule update --init``; -* (Optionally) Install the bundle docs and CMF docs: ``bash install.sh``; -* Run ``make html`` and view the generated HTML in the ``build`` directory. +.. code-block:: text + + .. versionadded:: 2.3 + The ``askHiddenResponse`` method was introduced in Symfony 2.3. + + You can also ask a question and hide the response. This is particularly [...] + +If you're documenting a behavior change, it may be helpful to *briefly* describe +how the behavior has changed. + +.. code-block:: text + + .. versionadded:: 2.3 + The ``include()`` function is a new Twig feature that's available in + Symfony 2.3. Prior, the ``{% include %}`` tag was used. + +Whenever a new minor version of Symfony is released (e.g. 2.4, 2.5, etc), +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. + +Testing Documentation +~~~~~~~~~~~~~~~~~~~~~ -.. _reStructuredText: http://docutils.sourceforge.net/rst.html -.. _Sphinx: http://sphinx-doc.org/ -.. _documents: https://github.com/symfony/symfony-docs -.. _reStructuredText Primer: http://sphinx-doc.org/rest.html -.. _markup: http://sphinx-doc.org/markup/ -.. _Pygments website: http://pygments.org/languages/ -.. _Sphinx quick setup: http://sphinx-doc.org/tutorial.html#setting-up-the-documentation-sources +When submitting a new content to the documentation repository or when changing +any existing resource, an automatic process will check if your documentation is +free of syntax errors and is ready to be reviewed. + +Nevertheless, if you prefer to do this check locally on your own machine before +submitting your documentation, follow these steps: + +* Install Sphinx_; +* Install the Sphinx extensions using git submodules: ``$ git submodule update --init``; +* (Optionally) Install the bundle docs and CMF docs: ``$ bash install.sh``; +* Run ``make html`` and view the generated HTML in the ``build/`` directory. + +.. _reStructuredText: http://docutils.sourceforge.net/rst.html +.. _Sphinx: http://sphinx-doc.org/ +.. _`Symfony documentation`: https://github.com/symfony/symfony-docs +.. _`reStructuredText Primer`: http://sphinx-doc.org/rest.html +.. _`reStructuredText Reference`: http://docutils.sourceforge.net/docs/user/rst/quickref.html +.. _`Sphinx Markup Constructs`: http://sphinx-doc.org/markup/ +.. _`supported languages`: http://pygments.org/languages/ diff --git a/contributing/documentation/license.rst b/contributing/documentation/license.rst index c8bce4bdaea..257693ab371 100644 --- a/contributing/documentation/license.rst +++ b/contributing/documentation/license.rst @@ -2,7 +2,7 @@ Symfony2 Documentation License ============================== The Symfony2 documentation is licensed under a Creative Commons -Attribution-Share Alike 3.0 Unported `License`_. +Attribution-Share Alike 3.0 Unported License (`CC BY-SA 3.0`_). **You are free:** @@ -46,5 +46,5 @@ Attribution-Share Alike 3.0 Unported `License`_. This is a human-readable summary of the `Legal Code (the full license)`_. -.. _License: http://creativecommons.org/licenses/by-sa/3.0/ +.. _`CC BY-SA 3.0`: http://creativecommons.org/licenses/by-sa/3.0/ .. _Legal Code (the full license): http://creativecommons.org/licenses/by-sa/3.0/legalcode diff --git a/contributing/documentation/overview.rst b/contributing/documentation/overview.rst index 8796557e56d..b01d4f94d54 100644 --- a/contributing/documentation/overview.rst +++ b/contributing/documentation/overview.rst @@ -1,101 +1,102 @@ Contributing to the Documentation ================================= -Documentation is as important as code. It follows the exact same principles: -DRY, tests, ease of maintenance, extensibility, optimization, and refactoring -just to name a few. And of course, documentation has bugs, typos, hard to read -tutorials, and more. +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. -Contributing ------------- +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. +This guide will explain everything you need to contribute to the Symfony +documentation. -Before contributing, you need to become familiar with the :doc:`markup -language ` used by the documentation. +Before Your First Contribution +------------------------------ -The Symfony2 documentation is hosted on GitHub: +**Before contributing**, you should consider the following: -.. code-block:: text - - https://github.com/symfony/symfony-docs +* Symfony documentation is written using reStructuredText_ markup language. + If you are not familiar with this format, read :doc:`this article ` + for a quick overview of its basic features. +* Symfony documentation is hosted on GitHub_. You'll need a GitHub user account + to contribute to the documentation. +* Symfony documentation is published under a + :doc:`Creative Commons BY-SA 3.0 License ` + and all your contributions will implicitly adhere to that license. -If you want to submit a patch, `fork`_ the official repository on GitHub and -then clone your fork: +Your First Documentation Contribution +------------------------------------- -.. code-block:: bash +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. - $ git clone git://github.com/YOURUSERNAME/symfony-docs.git +Let's imagine that you want to improve the installation chapter of the Symfony +book. In order to make your changes, follow these steps: -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. +**Step 1.** Go to the official Symfony documentation repository located at +`github.com/symfony/symfony-docs`_ and `fork the repository`_ to your personal +account. This is only needed the first time you contribute to Symfony. -Unless you're documenting a feature that was introduced *after* Symfony 2.3 -(e.g. in Symfony 2.4), your changes should always be based on the 2.3 branch. -To do this checkout the 2.3 branch before the next step: +**Step 2.** **Clone** the forked repository to your local machine (this +example uses the ``projects/symfony-docs/`` directory to store the documentation; +change this value accordingly): .. code-block:: bash - $ git checkout 2.3 - -.. tip:: - - Your base branch (e.g. 2.3) will become the "Applies to" in the :ref:`doc-contributing-pr-format` - that you'll use later. + $ cd projects/ + $ git clone git://github.com//symfony-docs.git -Next, create a dedicated branch for your changes (for organization): +**Step 3.** Switch to the **oldest maintained branch** before making any change. +Nowadays this is the ``2.3`` branch: .. code-block:: bash - $ git checkout -b improving_foo_and_bar - -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. - -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. + $ cd symfony-docs/ + $ git checkout 2.3 -If you have made your changes based on the 2.3 branch then you need to change -the base branch to be 2.3 on the preview page by clicking the ``edit`` button -on the top left: +If you are instead documenting a new feature, switch to the first Symfony +version which included it: ``2.5``, ``2.6``, etc. -.. image:: /images/docs-pull-request-change-base.png - :align: center +**Step 4.** Create a dedicated **new branch** for your changes. This greatly +simplifies the work of reviewing and merging your changes. Use a short and +memorable name for the new branch: -.. note:: +.. code-block:: bash - All changes made to a branch (e.g. 2.3) will be merged up to each "newer" - branch (e.g. 2.4, master, etc) for the next release on a weekly basis. + $ git checkout -b improve_install_chapter -GitHub covers the topic of `pull requests`_ in detail. +**Step 5.** Now make your changes in the documentation. Add, tweak, reword and +even remove any content, but make sure that you comply with the +doc:`/contributing/documentation/standards`. -.. note:: +**Step 6.** **Push** the changes to your forked repository: - The Symfony2 documentation is licensed under a Creative Commons - Attribution-Share Alike 3.0 Unported :doc:`License `. +.. code-block:: bash -You can also prefix the title of your pull request in a few cases: + $ git commit book/installation.rst + $ git push origin improve_install_chapter -* ``[WIP]`` (Work in Progress) is used when you are not yet finished with your - pull request, but you would like it to be reviewed. The pull request won't - be merged until you say it is ready. +**Step 7.** Everything is now ready to initiate a **pull request**. Go to your +forked repository at ``https//github.com//symfony-docs`` +and click on the ``Pull Requests`` link located in the sidebar. -* ``[WCM]`` (Waiting Code Merge) is used when you're documenting a new feature - or change that hasn't been accepted yet into the core code. The pull request - will not be merged until it is merged in the core code (or closed if the - change is rejected). +Then, click on the big ``New pull request`` button. As GitHub cannot guess the +exact changes that you want to propose, select the appropriate branches where +changes should be applied:º -.. _doc-contributing-pr-format: +.. image:: /images/docs-pull-request-change-base.png + :align: center -Pull Request Format -~~~~~~~~~~~~~~~~~~~ +In this example, the **base repository** should be ``symfony/symfony-docs`` and +the **base branch** should be the ``2.3``, which is the branch that you selected +to base your changes on. The **compare repository** should be your forked copy +of ``symfony-docs`` and the **compare branch** should be ``improve_install_chapter``, +which is the name of the branch you created and where you made your changes. -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: +**Step 8.** The last step is to prepare the **description** of the pull request. +To ensure that your work is reviewed quickly, please add the following table +at the beginning of your pull request description: .. code-block:: text @@ -106,123 +107,198 @@ into the documentation as quickly as possible: | 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: +In this example, this table would look as follows: .. code-block:: text | Q | A | ------------- | --- | Doc fix? | yes - | New docs? | yes (symfony/symfony#2500) - | Applies to | all (or 2.3+) - | Fixed tickets | #1075 + | New docs? | no + | Applies to | all + | Fixed tickets | #10575 -.. tip:: +**Step 9.** Now that you've successfully submitted your first contribution to the +Symfony documentation, **go and celebrate!** The documentation managers will +carefully review your work in short time and they will let you know about any +required change. - Please be patient. It can take from 15 minutes to several days for your changes - to appear on the symfony.com website after the documentation team merges your - pull request. You can check if your changes have introduced some markup issues - by going to the `Documentation Build Errors`_ page (it is updated each French - night at 3AM when the server rebuilds the documentation). +In case you need to add or modify anything, there is no need to create a new +pull request. Just make sure that you are on the correct branch, make your +changes and push them: -Documenting new Features or Behavior Changes --------------------------------------------- +.. code-block:: bash -If you're documenting a brand new feature or a change that's been made in -Symfony2, you should precede your description of the change with a ``.. versionadded:: 2.X`` -tag and a short description: + $ cd projects/symfony-docs/ + $ git checkout improve_install_chapter -.. code-block:: text + # ... do your changes - .. versionadded:: 2.3 - The ``askHiddenResponse`` method was introduced in Symfony 2.3. + $ git push - You can also ask a question and hide the response. This is particularly... +**Step 10.** After your pull request is eventually accepted and merged in the Symfony +documentation, you will be included in the `Symfony Documentation Contributors`_ +list. Moreover, if you happen to have a SensioLabsConnect_ profile, you will +get a cool `Symfony Documentation Badge`_. -If you're documenting a behavior change, it may be helpful to *briefly* describe -how the behavior has changed. +Your Second Documentation Contribution +-------------------------------------- -.. code-block:: text +The first contribution took some time because you had to fork the repository, +learn how to write documentation, comply with the pull requests standards, etc. +The second contribution will be much easier, except for one detail: given the +furious update activity of the Symfony documentation repository, odds are that +your fork is now out of date with the official repository. + +Solving this problem requires you to `sync your fork`_ with the original repository. +To do this, execute this command first to tell git about the original repository: + +.. code-block:: bash + + $ cd projects/symfony-docs/ + $ git remote add upstream https://github.com/symfony/symfony-docs.git + +Now you can **sync your fork** by executing the following command: + +.. code-block:: bash + + $ cd projects/symfony-docs/ + $ git fetch upstream + $ git checkout master + $ git merge upstream/master - .. versionadded:: 2.3 - The ``include()`` function is a new Twig feature that's available in - Symfony 2.3. Prior, the ``{% include %}`` tag was used. +Great! Now you can proceed by following the same steps explained in the previous +section: -Whenever a new minor version of Symfony2 is released (e.g. 2.4, 2.5, etc), -a new branch of the documentation is created from the ``master`` branch. -At this point, all the ``versionadded`` tags for Symfony2 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. +.. code-block:: bash -Standards ---------- + # create a new branch to store your changes based on the 2.3 branch + $ cd projects/symfony-docs/ + $ git checkout 2.3 + $ git checkout -b my_changes + + # ... do your changes + + # submit the changes to your forked repository + $ git add xxx.rst # (optional) only if this is a new content + $ git commit xxx.rst + $ git push + + # go to GitHub and create the Pull Request + # + # Include this table in the description: + # | 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] + +Your second contribution is now complete, so **go and celebrate again!** +You can also see how your ranking improves in the list of +`Symfony Documentation Contributors`_. + +Your Next Documentation Contributions +------------------------------------- + +Now that you've made two contributions to the Symfony documentation, you are +probably comfortable with all the Git-magic involved in the process. That's +why your next contributions would be much faster. Here you can find the complete +steps to contribute to the Symfony documentation, which you can use as a +**checklist**: -All documentation in the Symfony Documentation should follow -:doc:`the documentation standards `. +.. code-block:: bash -Reporting an Issue ------------------- + # sync your fork with the official Symfony repository + $ cd projects/symfony-docs/ + $ git fetch upstream + $ git checkout master + $ git merge upstream/master -The most easy contribution you can make is reporting issues: a typo, a grammar -mistake, a bug in a code example, a missing explanation, and so on. + # create a new branch from the oldest maintained version + $ git checkout 2.3 + $ git checkout -b my_changes -Steps: + # ... do your changes -* Submit a bug in the bug tracker; + # add and commit your changes + $ git add xxx.rst # (optional) only if this is a new content + $ git commit xxx.rst + $ git push -* *(optional)* Submit a patch. + # go to GitHub and create the Pull Request + # + # Include this table in the description: + # | 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] -Translating ------------ + # (optional) make the changes requested by reviewers and commit them + $ git commit xxx.rst + $ git push -Read the dedicated :doc:`document `. +You guessed right: after all this hard work, it's **time to celebrate again!** -Managing Releases ------------------ +Frequently Asked Questions +-------------------------- -Symfony has a very standardized release process, which you can read more -about in the :doc:`/contributing/community/releases` section. +Why Do my Changes Take so Long to Be Reviewed and/or Merged? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -To keep up with the release process, the documentation team makes several -changes to the documentation at various parts of the lifecycle. +Please be patient. It can take up to several days before your pull request can +be fully reviewed. After merging the changes, it could take again several hours +before your changes appear on the symfony.com website. -When a Release Reaches "End of Maintenance" -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +What If I Want to Translate Some Documentation into my Language? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Every release will eventually reach its "end of maintenance". For details, -see :ref:`contributing-release-maintenance`. +Read the dedicated :doc:`document `. -When a release reaches its end of maintenance, the following items are done. -For this example, suppose version 2.1 has just reached its end of maintenance: +Why Should I Use the Oldest Maintained Branch Instead of the Master Branch? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -* Changes and pull requests are no longer merged into to the branch (2.1), - except for security updates, which are merged until the release reaches - its "end of life". +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. -* All branches still under maintenance (e.g. 2.2 and higher) are updated - to reflect that pull requests should start from the now-oldest maintained - version (e.g. 2.2) - including the details in the README file. +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 +will use the necessary Git-magic to also apply your changes to all the active +branches of the documentation. -* Remove all ``versionadded`` directives - and any other notes related to features - changing or being new - for the version (e.g. 2.1) from the master branch. - The result is that the next release (which is the first that comes entirely - *after* the end of maintenance of this branch), will have no mentions of - the old version (e.g. 2.1). +What If I Want to Submit my Work without Fully Finishing It? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -When a new Branch is Created for a Release -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +You can do it. But please use one of these two prefixes to let reviewers know +about the state of your work: -During the :ref:`stabilization phase `, a -new branch on the documentation is created. For example, if version 2.3 were -being stabilized, then a new 2.3 branch would be created for it. When this -happens, the following items are done: +* ``[WIP]`` (Work in Progress) is used when you are not yet finished with your + pull request, but you would like it to be reviewed. The pull request won't + be merged until you say it is ready. -* Change all version and master references to the correct version (e.g. 2.3). - For example, in installation chapters, we reference the version you should - use for installation. As an example, see the changes made in `PR #2688`_. +* ``[WCM]`` (Waiting Code Merge) is used when you're documenting a new feature + or change that hasn't been accepted yet into the core code. The pull request + will not be merged until it is merged in the core code (or closed if the + change is rejected). -.. _`fork`: https://help.github.com/articles/fork-a-repo -.. _`pull requests`: https://help.github.com/articles/using-pull-requests -.. _`Documentation Build Errors`: http://symfony.com/doc/build_errors -.. _`PR #2688`: https://github.com/symfony/symfony-docs/pull/2688 +Would You Accept a Huge Pull Request with Lots of Changes? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +First, make sure that the changes are somewhat related. Otherwise, please create +separate pull requests. Anyway, before submitting a huge change, it's probably a +good idea to open an issue in the Symfony Documentation repository to ask the +managers if they agree with your proposed changes. Otherwise, they could refuse +your proposal after you put all that hard work into making the changes. We +definitely don't want you to waste your time! + +.. _`github.com/symfony/symfony-docs`: https://github.com/symfony/symfony-docs +.. _reStructuredText: http://docutils.sourceforge.net/rst.html +.. _GitHub: https://github.com/ +.. _`fork the repository`: https://help.github.com/articles/fork-a-repo +.. _`Symfony Documentation Contributors`: http://symfony.com/contributors/doc +.. _SensioLabsConnect: https://connect.sensiolabs.com/ +.. _`Symfony Documentation Badge`: https://connect.sensiolabs.com/badge/36/symfony-documentation-contributor +.. _`sync your fork`: https://help.github.com/articles/syncing-a-fork diff --git a/contributing/documentation/standards.rst b/contributing/documentation/standards.rst index 7e888fd9796..39d073ec0da 100644 --- a/contributing/documentation/standards.rst +++ b/contributing/documentation/standards.rst @@ -43,7 +43,7 @@ Example echo 'You cannot use the :: shortcut here'; - .. _`Symfony Documentation`: http://symfony.com/doc/current/contributing/documentation/standards.html + .. _`Symfony Documentation`: http://symfony.com/doc Code Examples ------------- @@ -134,19 +134,23 @@ Files and Directories ├─ vendor/ └─ ... -Language Standards ------------------- +English Language Standards +-------------------------- -* For sections, use the following capitalization rules: - `Capitalization of the first word, and all other words, except for closed-class words`_: +* **English Dialect**: use the United States English dialect, commonly called + `American English`_. +* **Section titles**: use a variant of the title case, where the first + word is always capitalized and all other words are capitalized, except for + the closed-class words (read Wikipedia article about `headings and titles`_). - The Vitamins are in my Fresh California Raisins + E.g.: The Vitamins are in my Fresh California Raisins -* Do not use `Serial (Oxford) Commas`_; -* You should use a form of *you* instead of *we* (i.e. avoid the first person - point of view: use the second instead); -* When referencing a hypothetical person, such as "a user with a session cookie", gender-neutral - pronouns (they/their/them) should be used. For example, instead of: +* **Punctuation**: avoid the use of `Serial (Oxford) Commas`_; +* **Pronouns**: avoid the use of `nosism`_ and always use *you* instead of *we*. + (i.e. avoid the first person point of view: use the second instead); +* **Gender-neutral language**: when referencing a hypothetical person, such as + *"a user with a session cookie"*, use gender-neutral pronouns (they/their/them). + For example, instead of: * he or she, use they * him or her, use them * his or her, use their @@ -155,5 +159,7 @@ Language Standards .. _`the Sphinx documentation`: http://sphinx-doc.org/rest.html#source-code .. _`Twig Coding Standards`: http://twig.sensiolabs.org/doc/coding_standards.html -.. _`Capitalization of the first word, and all other words, except for closed-class words`: http://en.wikipedia.org/wiki/Letter_case#Headings_and_publication_titles +.. _`American English`: http://en.wikipedia.org/wiki/American_English +.. _`headings and titles`: http://en.wikipedia.org/wiki/Letter_case#Headings_and_publication_titles .. _`Serial (Oxford) Commas`: http://en.wikipedia.org/wiki/Serial_comma +.. _`nosism`: http://en.wikipedia.org/wiki/Nosism diff --git a/contributing/documentation/translations.rst b/contributing/documentation/translations.rst index c1c434ce35b..efc14db51e0 100644 --- a/contributing/documentation/translations.rst +++ b/contributing/documentation/translations.rst @@ -4,11 +4,17 @@ Translations The Symfony2 documentation is written in English and many people are involved in the translation process. +.. note:: + + Symfony Project officially discourages starting new translations for the + documentation. As a matter of fact, there is `an ongoing discussion`_ in + the community about the benefits and drawbacks of community driven translations. + Contributing ------------ -First, become familiar with the :doc:`markup language ` used by the -documentation. +First, become familiar with the :doc:`markup language ` +used by the documentation. Then, subscribe to the `Symfony docs mailing-list`_, as collaboration happens there. @@ -84,4 +90,5 @@ repository and apply changes to the translated documents as soon as possible. Non maintained languages are removed from the official list of repositories as obsolete documentation is dangerous. +.. _`an ongoing discussion`: https://github.com/symfony/symfony-docs/issues/4078 .. _Symfony docs mailing-list: http://groups.google.com/group/symfony-docs