Skip to content

Commit

Permalink
[Contributing] Several tweaks
Browse files Browse the repository at this point in the history
  • Loading branch information
xelaris committed Jan 18, 2015
1 parent 9fee9ee commit 8be88af
Show file tree
Hide file tree
Showing 4 changed files with 35 additions and 15 deletions.
3 changes: 2 additions & 1 deletion contributing/documentation/format.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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`_.
Expand Down Expand Up @@ -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
Expand Down
33 changes: 24 additions & 9 deletions contributing/documentation/overview.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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/<YOUR GITHUB USERNAME>/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:
Expand Down Expand Up @@ -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
#
Expand Down Expand Up @@ -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
#
Expand All @@ -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
--------------------------

Expand Down
12 changes: 8 additions & 4 deletions contributing/documentation/standards.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -77,8 +79,9 @@ Configuration examples should show all supported formats using
:ref:`configuration blocks <docs-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

Expand Down Expand Up @@ -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
Expand Down
2 changes: 1 addition & 1 deletion contributing/documentation/translations.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand Down

0 comments on commit 8be88af

Please sign in to comment.