From 8be88af2f7a7a6c553a0b47fa9bce04a5ffe82b1 Mon Sep 17 00:00:00 2001 From: Alexander Schwenn Date: Thu, 8 Jan 2015 02:08:20 +0100 Subject: [PATCH] [Contributing] Several tweaks --- contributing/documentation/format.rst | 3 +- contributing/documentation/overview.rst | 33 +++++++++++++++------ contributing/documentation/standards.rst | 12 +++++--- contributing/documentation/translations.rst | 2 +- 4 files changed, 35 insertions(+), 15 deletions(-) diff --git a/contributing/documentation/format.rst b/contributing/documentation/format.rst index eeedf1e00dd..4bb8fe4bb61 100644 --- a/contributing/documentation/format.rst +++ b/contributing/documentation/format.rst @@ -11,6 +11,7 @@ reStructuredText 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`_ +in raw format. If you want to learn more about this format, check out the `reStructuredText Primer`_ tutorial and the `reStructuredText Reference`_. @@ -182,7 +183,7 @@ Symfony, you should precede your description of the change with a 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. +how the behavior has changed: .. code-block:: rst diff --git a/contributing/documentation/overview.rst b/contributing/documentation/overview.rst index e610df1b994..f7cd0608926 100644 --- a/contributing/documentation/overview.rst +++ b/contributing/documentation/overview.rst @@ -79,19 +79,19 @@ even remove any content, but make sure that you comply with the **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. +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 +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/contributing/docs-pull-request-change-base.png :align: center -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``, +In this example, the **base fork** 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 **head fork** 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. .. _pull-request-format: @@ -188,7 +188,7 @@ section: # 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 + $ git push origin my_changes # go to GitHub and create the Pull Request # @@ -230,7 +230,7 @@ steps to contribute to the Symfony documentation, which you can use as a # add and commit your changes $ git add xxx.rst # (optional) only if this is a new content $ git commit xxx.rst - $ git push + $ git push origin my_changes # go to GitHub and create the Pull Request # @@ -248,6 +248,21 @@ steps to contribute to the Symfony documentation, which you can use as a You guessed right: after all this hard work, it's **time to celebrate again!** +Minor Changes (e.g. Typos) +-------------------------- + +You may find just a typo and want to fix it. Due to GitHub's functional +frontend, it is quite simple to create Pull Requests right in your +browser while reading the docs on symfony.com. To do this, just click +the **edit this page** button on the upper right corner. Beforehand, +please switch to the right branch as mentioned before. Now you are able +to edit the content and describe your changes within the GitHub +frontend. When your work is done, click **Propose file change** to +create a commit and, in case it is your first contribution, also your +fork. A new branch is created automatically in order to provide a base +for your Pull Request. Then fill out the form to create the Pull Request +as described above. + Frequently Asked Questions -------------------------- diff --git a/contributing/documentation/standards.rst b/contributing/documentation/standards.rst index 39d073ec0da..2a1b10e28f5 100644 --- a/contributing/documentation/standards.rst +++ b/contributing/documentation/standards.rst @@ -58,8 +58,10 @@ Code Examples * When you fold a part of a line, e.g. a variable value, put ``...`` (without comment) at the place of the fold; * Description of the folded code: (optional) - If you fold several lines: the description of the fold can be placed after the ``...`` - If you fold only part of a line: the description can be placed before the line; + + * If you fold several lines: the description of the fold can be placed after the ``...``; + * If you fold only part of a line: the description can be placed before the line; + * If useful to the reader, a PHP code example should start with the namespace declaration; * When referencing classes, be sure to show the ``use`` statements at the @@ -77,8 +79,9 @@ Configuration examples should show all supported formats using :ref:`configuration blocks `. The supported formats (and their orders) are: -* **Configuration** (including services and routing): YAML, XML, PHP -* **Validation**: YAML, Annotations, XML, PHP +* **Configuration** (including services): YAML, XML, PHP +* **Routing**: Annotations, YAML, XML, PHP +* **Validation**: Annotations, YAML, XML, PHP * **Doctrine Mapping**: Annotations, YAML, XML, PHP * **Translation**: XML, YAML, PHP @@ -151,6 +154,7 @@ English Language Standards * **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 diff --git a/contributing/documentation/translations.rst b/contributing/documentation/translations.rst index 54c5002ff54..f6951d228c4 100644 --- a/contributing/documentation/translations.rst +++ b/contributing/documentation/translations.rst @@ -6,7 +6,7 @@ in the translation process. .. note:: - Symfony Project officially discourages starting new translations for the + Symfony Project officially discourages from 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.