From 723603c851d21594d0b171982347ad149f87bd06 Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Sat, 13 Sep 2014 10:55:20 +0200 Subject: [PATCH 01/10] Revamped the documentation about "Contributing Docs" --- contributing/documentation/format.rst | 134 ++++++--- contributing/documentation/license.rst | 4 +- contributing/documentation/overview.rst | 366 ++++++++++++++--------- contributing/documentation/standards.rst | 30 +- 4 files changed, 326 insertions(+), 208 deletions(-) diff --git a/contributing/documentation/format.rst b/contributing/documentation/format.rst index 491d27df407..67b8dcb5e4d 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 prefer 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: +**Links to the API** follow a different syntax, where you must specify the type +of linked resource (``namespace``, ``class`` or ``method``): .. code-block:: rst @@ -148,7 +153,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 +163,55 @@ and to the PHP documentation: :phpfunction:`iterator_to_array` +New Features or Behavior Changes +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +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`` directive and a short description: + +.. 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 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. + Testing Documentation ~~~~~~~~~~~~~~~~~~~~~ -To test documentation before a commit: +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/ -.. _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 +* 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..ec829db431a 100644 --- a/contributing/documentation/overview.rst +++ b/contributing/documentation/overview.rst @@ -1,101 +1,101 @@ 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 we dedicate a great amount of resources to +document new features and to maintain updated the rest of the documentation. -Contributing ------------- +More than 800 hundred developers all around the world have contributed to +Symfony documentation, and we are glad that you are considering joining this big +family. This guide will explain everything you need to contribute to 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 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 Symfony documentation for the +first time. Next section will explain the abbreviated process to follow for the +next contributions. - $ 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 do those 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 (in this +example we'll use the ``projects/symfony-docs/`` directory to store the +documentation; change this value accordingly): .. code-block:: bash - $ git checkout 2.3 + $ cd projects/ + $ git clone git://github.com//symfony-docs.git -.. 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. - -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 were 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:`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 -* ``[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 at 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 that you selected to work on 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, you have to add the following table +at the beginning of your pull request description: .. code-block:: text @@ -106,123 +106,195 @@ 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 | 2.3+ + | 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 in 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, we will +award you 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 outdated comparing it with the official repository. + +Solving this problem requires to `sync your fork`_ with the original repository. +To do so, execute first this command to tell git which is the original repository +from which you created the fork: + +.. code-block:: bash + + $ cd projects/symfony-docs/ + $ git remote add upstream https://github.com/symfony/symfony-docs.git + +Now you can **sync your fork** executing the following command: - .. versionadded:: 2.3 - The ``include()`` function is a new Twig feature that's available in - Symfony 2.3. Prior, the ``{% include %}`` tag was used. +.. code-block:: bash -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. + $ cd projects/symfony-docs/ + $ git fetch upstream + $ git checkout master + $ git merge upstream/master -Standards ---------- +Now you can proceed following the same steps explained in the previous section: -All documentation in the Symfony Documentation should follow -:doc:`the documentation standards `. +.. code-block:: bash -Reporting an Issue ------------------- + # 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 completed, so **go and celebrate again!** +You will 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 and easier. Here you can find +the complete steps to contribute to Symfony documentation, which you can use as +a **checklist**: -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. +.. code-block:: bash -Steps: + # sync your fork with the official Symfony repository + $ cd projects/symfony-docs/ + $ git fetch upstream + $ git checkout master + $ git merge upstream/master -* Submit a bug in the bug tracker; + # create a new branch from the oldest maintained version + $ git checkout 2.3 + $ git checkout -b my_changes -* *(optional)* Submit a patch. + # do your changes ... -Translating ------------ + # add and commit your changes + $ git add xxx.rst # (optional) only if this is a new content + $ git commit xxx.rst + $ git push -Read the dedicated :doc:`document `. + # 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] -Managing Releases ------------------ + # (optional) make the changes requested by reviewers and commit them + $ git commit xxx.rst + $ git push -Symfony has a very standardized release process, which you can read more -about in the :doc:`/contributing/community/releases` section. +You guessed right: after all this hard work, it's **time to celebrate again!** -To keep up with the release process, the documentation team makes several -changes to the documentation at various parts of the lifecycle. +Frequently Asked Questions +-------------------------- -When a Release Reaches "End of Maintenance" -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Why Do my Changes so Long to Be Reviewed and/or Merged? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Every release will eventually reach its "end of maintenance". For details, -see :ref:`contributing-release-maintenance`. +Please be patient. It can take from 15 minutes to several days before your pull +request can be fully reviewed. And after merging the changes, it could take again +from some minutes to several hours before your changes appear on the symfony.com +website. -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: +What If I Want to Translate Some Documentation into my Language? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -* 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". +Read the dedicated :doc:`document `. + +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. -* 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? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +You can do it. But please use one of these two prefixes to let reviewers know +which is the state of your work: + +* ``[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. -When a new Branch is Created for a Release -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +* ``[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). -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: +Would You Admit a Huge Pull Request with Lots of Changes? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -* 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`_. +Sure! But before doing 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 having +made all the work and you would have wasted a lot of time. -.. _`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 +.. _`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..bc4a0980848 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 From 53c3a1689e0f59b4fc1b082cc0f0e9cbd2ecd16d Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Sat, 13 Sep 2014 11:01:19 +0200 Subject: [PATCH 02/10] Added missing link --- contributing/documentation/overview.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/contributing/documentation/overview.rst b/contributing/documentation/overview.rst index ec829db431a..9dc6d81e6a4 100644 --- a/contributing/documentation/overview.rst +++ b/contributing/documentation/overview.rst @@ -292,6 +292,7 @@ in the Symfony Documentation repository to ask the managers if they agree with your proposed changes. Otherwise, they could refuse your proposal after having made all the work and you would have wasted a lot of time. +.. _`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 From 4751eb9dd06cc3b5dbd307f2eec44b2ef4bea97c Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Sat, 13 Sep 2014 11:10:31 +0200 Subject: [PATCH 03/10] lways use absolute links instead of relative for internal doc links --- contributing/documentation/overview.rst | 14 +++++++------- contributing/documentation/translations.rst | 4 ++-- 2 files changed, 9 insertions(+), 9 deletions(-) diff --git a/contributing/documentation/overview.rst b/contributing/documentation/overview.rst index 9dc6d81e6a4..ddde25185c0 100644 --- a/contributing/documentation/overview.rst +++ b/contributing/documentation/overview.rst @@ -5,10 +5,9 @@ One of the essential principles of the Symfony project is that **documentation i as important as code**. That's why we dedicate a great amount of resources to document new features and to maintain updated the rest of the documentation. -More than 800 hundred developers all around the world have contributed to -Symfony documentation, and we are glad that you are considering joining this big -family. This guide will explain everything you need to contribute to Symfony -documentation. +More than 800 developers all around the world have contributed to Symfony +documentation, and we are glad that you are considering joining this big family. +This guide will explain everything you need to contribute to Symfony documentation. Before Your First Contribution ------------------------------ @@ -16,11 +15,12 @@ Before Your First Contribution **Before contributing**, you should consider the following: * Symfony documentation is written using `reStructuredText`_ markup language. - If you are not familiar with this format, read :doc:`this article ` + 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 documentation. -* Symfony documentation is published under a :doc:`Creative Commons BY-SA 3.0 License ` +* Symfony documentation is published under a + :doc:`Creative Commons BY-SA 3.0 License ` and all your contributions will implicitly adhere to that license. Your First Documentation Contribution @@ -255,7 +255,7 @@ website. What If I Want to Translate Some Documentation into my Language? ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Read the dedicated :doc:`document `. +Read the dedicated :doc:`document `. Why Should I Use the Oldest Maintained Branch Instead of the Master Branch? ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/contributing/documentation/translations.rst b/contributing/documentation/translations.rst index c1c434ce35b..caffed384f9 100644 --- a/contributing/documentation/translations.rst +++ b/contributing/documentation/translations.rst @@ -7,8 +7,8 @@ in the translation process. 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. From 79375aee9fc715b3026ec0523ce759ee4b94b6e6 Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Sat, 13 Sep 2014 11:16:08 +0200 Subject: [PATCH 04/10] Switched another relative link into an absolute reference --- contributing/documentation/overview.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/contributing/documentation/overview.rst b/contributing/documentation/overview.rst index ddde25185c0..7944b45a965 100644 --- a/contributing/documentation/overview.rst +++ b/contributing/documentation/overview.rst @@ -67,7 +67,8 @@ memorable name for the new branch: $ git checkout -b improve_install_chapter **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:`standards`. +even remove any content, but make sure that you comply with the +doc:`/contributing/documentation/standards`. **Step 6.** **Push** the changes to your forked repository: From 991ff6f6e8afb16cc509b0610838510da3387820 Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Sat, 13 Sep 2014 11:24:42 +0200 Subject: [PATCH 05/10] Added a note about not using relative internal links in the doc --- contributing/documentation/format.rst | 15 +++++++++++++-- 1 file changed, 13 insertions(+), 2 deletions(-) diff --git a/contributing/documentation/format.rst b/contributing/documentation/format.rst index 67b8dcb5e4d..122803a5b5e 100644 --- a/contributing/documentation/format.rst +++ b/contributing/documentation/format.rst @@ -123,7 +123,7 @@ Adding Links .. code-block:: rst - :doc:`/path/to/page` + :doc:`/absolute/path/to/page` The page name should not include the file extension (``.rst``). For example: @@ -135,7 +135,18 @@ The page name should not include the file extension (``.rst``). For example: :doc:`/cookbook/configuration/environments` -The title of the linked page will be automaticall used as the text of the link. +Although they are technically correct, avoid the use of relative internal links +such as the following: + +.. code-block:: rst + + :doc:`controller` + + :doc:`event_dispatcher/introduction` + + :doc:`environments` + +The title of the linked page will be automatically used as the text of the link. If you want to modify that title, use this alternative syntax: .. code-block:: rst From ff66e94a27c22a01b95e2f6360dcb95abc74da29 Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Sat, 13 Sep 2014 11:39:51 +0200 Subject: [PATCH 06/10] Added lots of fixes suggested by reviewers --- contributing/documentation/format.rst | 31 +++++++++++++++------------ 1 file changed, 17 insertions(+), 14 deletions(-) diff --git a/contributing/documentation/format.rst b/contributing/documentation/format.rst index 122803a5b5e..7edfe895848 100644 --- a/contributing/documentation/format.rst +++ b/contributing/documentation/format.rst @@ -119,7 +119,8 @@ Markup format Use it to display Adding Links ~~~~~~~~~~~~ -**Internal links** to other documentation pages use the following syntax: +The most common type of links are **internal links** to other documentation pages, +which use the following syntax: .. code-block:: rst @@ -135,23 +136,25 @@ The page name should not include the file extension (``.rst``). For example: :doc:`/cookbook/configuration/environments` -Although they are technically correct, avoid the use of relative internal links -such as the following: +The title of the linked page will be automatically used as the text of the link. +If you want to modify that title, use this alternative syntax: .. code-block:: rst - :doc:`controller` + :doc:`Spooling Email ` - :doc:`event_dispatcher/introduction` +.. note:: - :doc:`environments` + Although they are technically correct, avoid the use of relative internal + links such as the following: -The title of the linked page will be automatically used as the text of the link. -If you want to modify that title, use this alternative syntax: + .. code-block:: rst -.. code-block:: rst + :doc:`controller` - :doc:`Spooling Email ` + :doc:`event_dispatcher/introduction` + + :doc:`environments` **Links to the API** follow a different syntax, where you must specify the type of linked resource (``namespace``, ``class`` or ``method``): @@ -178,7 +181,7 @@ New Features or Behavior Changes ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 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 +Symfony, you should precede your description of the change with a ``.. versionadded:: 2.X`` directive and a short description: .. code-block:: text @@ -186,7 +189,7 @@ Symfony2, you should precede your description of the change with a .. 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... + 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. @@ -197,9 +200,9 @@ how the behavior has changed. 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 Symfony2 is released (e.g. 2.4, 2.5, etc), +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 Symfony2 versions that have +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. From 15f3c94221e415845381b86b81527e11235246cc Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Sat, 13 Sep 2014 11:58:36 +0200 Subject: [PATCH 07/10] Added another bunch of fixes suggested by reviewers --- contributing/documentation/overview.rst | 33 ++++++++++++------------- 1 file changed, 16 insertions(+), 17 deletions(-) diff --git a/contributing/documentation/overview.rst b/contributing/documentation/overview.rst index 7944b45a965..18dde8196fd 100644 --- a/contributing/documentation/overview.rst +++ b/contributing/documentation/overview.rst @@ -2,7 +2,7 @@ Contributing to the Documentation ================================= One of the essential principles of the Symfony project is that **documentation is -as important as code**. That's why we dedicate a great amount of resources to +as important as code**. That's why a great amount of resources are dedicated to document new features and to maintain updated the rest of the documentation. More than 800 developers all around the world have contributed to Symfony @@ -34,13 +34,12 @@ Let's imagine that you want to improve the installation chapter of the Symfony book. In order to do those changes, follow these steps: **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. +`github.com/symfony/symfony-docs`_ and `fork the repository`_ to your personal +account. This is only needed the first time you contribute to Symfony. -**Step 2.** **Clone** the forked repository to your local machine (in this -example we'll use the ``projects/symfony-docs/`` directory to store the -documentation; change this value accordingly): +**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 @@ -115,7 +114,7 @@ In this example, this table would look as follows: | ------------- | --- | Doc fix? | yes | New docs? | no - | Applies to | 2.3+ + | Applies to | all | Fixed tickets | #10575 **Step 9.** Now that you've successfully submitted your first contribution to the @@ -132,14 +131,14 @@ changes and push them: $ cd projects/symfony-docs/ $ git checkout improve_install_chapter - # do your changes ... + # ... do your changes $ git push **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, we will -award you a cool `Symfony Documentation Badge`_. +list. Moreover, if you happen to have a `SensioLabsConnect`_ profile, you will +get a cool `Symfony Documentation Badge`_. Your Second Documentation Contribution -------------------------------------- @@ -177,7 +176,7 @@ Now you can proceed following the same steps explained in the previous section: $ git checkout 2.3 $ git checkout -b my_changes - # do your changes ... + # ... do your changes # submit the changes to your forked repository $ git add xxx.rst # (optional) only if this is a new content @@ -219,7 +218,7 @@ a **checklist**: $ git checkout 2.3 $ git checkout -b my_changes - # do your changes ... + # ... do your changes # add and commit your changes $ git add xxx.rst # (optional) only if this is a new content @@ -248,10 +247,9 @@ Frequently Asked Questions Why Do my Changes so Long to Be Reviewed and/or Merged? ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Please be patient. It can take from 15 minutes to several days before your pull -request can be fully reviewed. And after merging the changes, it could take again -from some minutes to several hours before your changes appear on the symfony.com -website. +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. What If I Want to Translate Some Documentation into my Language? ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -293,6 +291,7 @@ in the Symfony Documentation repository to ask the managers if they agree with your proposed changes. Otherwise, they could refuse your proposal after having made all the work and you would have wasted a lot of 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 From 9bcd33d6d62f0637654f15aa231f8d3f07a054dd Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Sat, 13 Sep 2014 12:41:23 +0200 Subject: [PATCH 08/10] More and more fixes and improvements --- contributing/documentation/format.rst | 17 +++++++++-------- contributing/documentation/overview.rst | 21 +++++++++++---------- contributing/documentation/standards.rst | 2 +- contributing/documentation/translations.rst | 7 +++++++ 4 files changed, 28 insertions(+), 19 deletions(-) diff --git a/contributing/documentation/format.rst b/contributing/documentation/format.rst index 7edfe895848..ac76947c6c7 100644 --- a/contributing/documentation/format.rst +++ b/contributing/documentation/format.rst @@ -1,8 +1,8 @@ Documentation Format ==================== -The Symfony documentation uses `reStructuredText`_ as its markup language and -`Sphinx`_ for generating the documentation in the formats read by the end users, +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 @@ -12,7 +12,7 @@ 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`_ -If you prefer to learn more about this format, check out the `reStructuredText Primer`_ +If you want to learn more about this format, check out the `reStructuredText Primer`_ tutorial and the `reStructuredText Reference`_. .. caution:: @@ -64,7 +64,7 @@ Configuration Blocks Whenever you include a configuration sample, use the ``configuration-block`` directive to show the configuration in all supported configuration formats -(``PHP``, ``YAML``, and ``XML``). Example: +(``PHP``, ``YAML`` and ``XML``). Example: .. code-block:: rst @@ -146,7 +146,8 @@ If you want to modify that title, use this alternative syntax: .. note:: Although they are technically correct, avoid the use of relative internal - links such as the following: + links such as the following, because they break the references in the + generated PDF documentation: .. code-block:: rst @@ -217,13 +218,13 @@ 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 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/ +.. _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 diff --git a/contributing/documentation/overview.rst b/contributing/documentation/overview.rst index 18dde8196fd..c984c9e4930 100644 --- a/contributing/documentation/overview.rst +++ b/contributing/documentation/overview.rst @@ -14,10 +14,10 @@ Before Your First Contribution **Before contributing**, you should consider the following: -* Symfony documentation is written using `reStructuredText`_ markup language. +* 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 +* Symfony documentation is hosted on GitHub_. You'll need a GitHub user account to contribute documentation. * Symfony documentation is published under a :doc:`Creative Commons BY-SA 3.0 License ` @@ -137,7 +137,7 @@ changes and push them: **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 +list. Moreover, if you happen to have a SensioLabsConnect_ profile, you will get a cool `Symfony Documentation Badge`_. Your Second Documentation Contribution @@ -286,16 +286,17 @@ which is the state of your work: Would You Admit a Huge Pull Request with Lots of Changes? ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Sure! But before doing 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 having -made all the work and you would have wasted a lot of time. +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 having made all the work and you would have wasted a lot of time. .. _`github.com/symfony/symfony-docs`: https://github.com/symfony/symfony-docs -.. _`reStructuredText`: http://docutils.sourceforge.net/rst.html -.. _`GitHub`: https://github.com/ +.. _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/ +.. _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 bc4a0980848..39d073ec0da 100644 --- a/contributing/documentation/standards.rst +++ b/contributing/documentation/standards.rst @@ -140,7 +140,7 @@ English Language Standards * **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 + word is always capitalized and all other words are capitalized, except for the closed-class words (read Wikipedia article about `headings and titles`_). E.g.: The Vitamins are in my Fresh California Raisins diff --git a/contributing/documentation/translations.rst b/contributing/documentation/translations.rst index caffed384f9..efc14db51e0 100644 --- a/contributing/documentation/translations.rst +++ b/contributing/documentation/translations.rst @@ -4,6 +4,12 @@ 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 ------------ @@ -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 From baa06b53537f6278334b7586d31f4a967c57184b Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Mon, 15 Sep 2014 20:31:42 +0200 Subject: [PATCH 09/10] Removed two highlight formats which are "experimental" and not used by end users --- contributing/documentation/format.rst | 2 -- 1 file changed, 2 deletions(-) diff --git a/contributing/documentation/format.rst b/contributing/documentation/format.rst index ac76947c6c7..ebca7c672c9 100644 --- a/contributing/documentation/format.rst +++ b/contributing/documentation/format.rst @@ -112,8 +112,6 @@ Markup format Use it to display ``html+php`` PHP code blended with HTML ``ini`` INI ``php-annotations`` PHP Annotations -``php-standalone`` Pure PHP code -``php-symfony`` PHP code with special Symfony features =================== ====================================== Adding Links From 88ddbb16db781a9cec6fa759b532d8d07f162a11 Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Mon, 15 Sep 2014 20:42:36 +0200 Subject: [PATCH 10/10] Fixed all the errors found by Ryan --- contributing/documentation/format.rst | 2 +- contributing/documentation/overview.rst | 66 +++++++++++++------------ 2 files changed, 35 insertions(+), 33 deletions(-) diff --git a/contributing/documentation/format.rst b/contributing/documentation/format.rst index ebca7c672c9..4f464e85001 100644 --- a/contributing/documentation/format.rst +++ b/contributing/documentation/format.rst @@ -156,7 +156,7 @@ If you want to modify that title, use this alternative syntax: :doc:`environments` **Links to the API** follow a different syntax, where you must specify the type -of linked resource (``namespace``, ``class`` or ``method``): +of the linked resource (``namespace``, ``class`` or ``method``): .. code-block:: rst diff --git a/contributing/documentation/overview.rst b/contributing/documentation/overview.rst index c984c9e4930..b01d4f94d54 100644 --- a/contributing/documentation/overview.rst +++ b/contributing/documentation/overview.rst @@ -3,11 +3,12 @@ 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 -document new features and to maintain updated the rest of the documentation. +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 +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 Symfony documentation. +This guide will explain everything you need to contribute to the Symfony +documentation. Before Your First Contribution ------------------------------ @@ -18,7 +19,7 @@ Before Your First Contribution 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 documentation. + 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. @@ -26,12 +27,12 @@ Before Your First Contribution Your First Documentation Contribution ------------------------------------- -In this section you'll learn how to contribute to Symfony documentation for the -first time. Next section will explain the abbreviated process to follow for the -next contributions. +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. Let's imagine that you want to improve the installation chapter of the Symfony -book. In order to do those changes, follow these steps: +book. In order to make your changes, follow these steps: **Step 1.** Go to the official Symfony documentation repository located at `github.com/symfony/symfony-docs`_ and `fork the repository`_ to your personal @@ -54,7 +55,7 @@ Nowadays this is the ``2.3`` branch: $ cd symfony-docs/ $ git checkout 2.3 -If you were instead documenting a new feature, switch to the first Symfony +If you are instead documenting a new feature, switch to the first Symfony version which included it: ``2.5``, ``2.6``, etc. **Step 4.** Create a dedicated **new branch** for your changes. This greatly @@ -74,15 +75,15 @@ doc:`/contributing/documentation/standards`. .. code-block:: bash $ git commit book/installation.rst - $ git push + $ git push origin improve_install_chapter **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 at the sidebar. +and click on the ``Pull Requests`` link located in the sidebar. 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: +changes should be applied:º .. image:: /images/docs-pull-request-change-base.png :align: center @@ -91,10 +92,10 @@ 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 that you selected to work on your changes. +which is the name of the branch you created and where you made your changes. **Step 8.** The last step is to prepare the **description** of the pull request. -To ensure that your work is reviewed quickly, you have to add the following table +To ensure that your work is reviewed quickly, please add the following table at the beginning of your pull request description: .. code-block:: text @@ -123,7 +124,7 @@ carefully review your work in short time and they will let you know about any required change. 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 in the correct branch, make your +pull request. Just make sure that you are on the correct branch, make your changes and push them: .. code-block:: bash @@ -147,18 +148,17 @@ 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 outdated comparing it with the official repository. +your fork is now out of date with the official repository. -Solving this problem requires to `sync your fork`_ with the original repository. -To do so, execute first this command to tell git which is the original repository -from which you created the fork: +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** executing the following command: +Now you can **sync your fork** by executing the following command: .. code-block:: bash @@ -167,7 +167,8 @@ Now you can **sync your fork** executing the following command: $ git checkout master $ git merge upstream/master -Now you can proceed following the same steps explained in the previous section: +Great! Now you can proceed by following the same steps explained in the previous +section: .. code-block:: bash @@ -193,8 +194,8 @@ Now you can proceed following the same steps explained in the previous section: # | Applies to | [Symfony version numbers this applies to] # | Fixed tickets | [comma separated list of tickets fixed by the PR] -Your second contribution is now completed, so **go and celebrate again!** -You will also see how your ranking improves in the list of +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 @@ -202,9 +203,9 @@ 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 and easier. Here you can find -the complete steps to contribute to Symfony documentation, which you can use as -a **checklist**: +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**: .. code-block:: bash @@ -244,8 +245,8 @@ You guessed right: after all this hard work, it's **time to celebrate again!** Frequently Asked Questions -------------------------- -Why Do my Changes so Long to Be Reviewed and/or Merged? -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Why Do my Changes Take so Long to Be Reviewed and/or Merged? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 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 @@ -272,7 +273,7 @@ What If I Want to Submit my Work without Fully Finishing It? ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ You can do it. But please use one of these two prefixes to let reviewers know -which is the state of your work: +about the state of your work: * ``[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 @@ -283,14 +284,15 @@ which is the state of your work: will not be merged until it is merged in the core code (or closed if the change is rejected). -Would You Admit a Huge Pull Request with Lots of Changes? -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +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 having made all the work and you would have wasted a lot of time. +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