Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Simplified the contribution article for Symfony Docs #6367

Closed
wants to merge 7 commits into from
+128 −170
Closed

Simplified the contribution article for Symfony Docs #6367

Changes from 1 commit
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
870a3c1
Simplified the contribution article for Symfony Docs
javiereguiluz Mar 14, 2016
4c6b435
More simplifications
javiereguiluz Mar 16, 2016
1b55fd2
Added fixes recommended by reviewers
javiereguiluz Mar 20, 2016
27a5aee
Minor fixes
javiereguiluz May 21, 2016
2bb8909
Fixed a syntax issue
javiereguiluz May 21, 2016
cd4e9d2
Rewords and tweaks
javiereguiluz May 21, 2016
afbff88
More rewords
javiereguiluz May 21, 2016
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
268 changes: 104 additions & 164 deletions contributing/documentation/overview.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,11 +1,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
documenting new features and to keeping the rest of the documentation up-to-date.
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.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

"up-to-date" must be on one line. Otherwise, the newline is treated as a space.


More than 700 developers all around the world have contributed to Symfony's
More than 1,000 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.
Expand All @@ -15,11 +16,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 </contributing/documentation/format>`
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 written using `reStructuredText`_ markup language.
If you are not familiar with this format, read :doc:`this article
</contributing/documentation/format>` for a quick overview of its basic
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We usually don't wrap lines inside doc or ref roles.

features.
* Symfony documentation is hosted on `GitHub`_. You'll need a free GitHub user
account to contribute to the documentation.
* Symfony documentation is published under a
:doc:`Creative Commons BY-SA 3.0 License </contributing/documentation/license>`
and all your contributions will implicitly adhere to that license.
Expand All @@ -35,48 +37,82 @@ Let's imagine that you want to improve the installation chapter of the Symfony
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
account. This is only needed the first time you contribute to Symfony.
`github.com/symfony/symfony-docs`_ and click on the **Fork** button to `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 (this
example uses 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):
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I am not convinced that we should still describe the steps to clone the repository locally as the best solution. Imo it's much easier to just browse to the file you want to edit on GitHub, click the edit button and make the changes just inside the text editor provided by GitHub. Most of the times this should be sufficient and is a much more straightforward way to contribute.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

OK. I like your idea. In 4c6b435 commit I've changed some things. Thanks!

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

👍 Cool! I like that addition very much, Javier!

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@xabbuh depends whether you want to make small changes or big ones actually

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@stof Correct, and I think Javier wrote that quite perfectly:

This method is best suited for small contributions, such as typos and rewordings.


.. code-block:: bash

$ cd projects/
$ git clone git://github.com/<YOUR GITHUB USERNAME>/symfony-docs.git

**Step 3.** Switch to the **oldest maintained branch** before making any change.
Nowadays this is the ``2.3`` branch:
**Step 3.** Add the original Symfony docs repository as a "Git remote" executing
this command:

.. code-block:: bash

$ cd symfony-docs/
$ git checkout 2.3
$ git remote add upstream https://github.com/symfony/symfony-docs.git

If things went right, you'll see the following when listing the "remotes" of
your project:

.. code-block:: bash

If you are instead documenting a new feature, switch to the first Symfony
version which included it: ``2.5``, ``2.6``, etc.
$ git remote -v
origin https://github.com/<YOUR GITHUB USERNAME>/symfony-docs.git (fetch)
origin https://github.com/<YOUR GITHUB USERNAME>/symfony-docs.git (push)
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

For your own repository, their shouldn't be HTTPS URLs (we cloned using Git over SSH before).

upstream https://github.com/symfony/symfony-docs.git (fetch)
upstream https://github.com/symfony/symfony-docs.git (push)

**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:
The purpose of this step is to allow you work simultaneously on the official
Symfony repository and on your own fork. You'll see this in action in a moment.

**Step 4.** Create a dedicated **new branch** for your changes. Use a short and
memorable name for the new branch (if you are fixing a reported issue, use
``fix_XXX`` as the branch name, where ``XXX`` is the number of the issue):

.. code-block:: bash

$ git checkout -b improve_install_chapter
$ git checkout -b improve_install_chapter upstream/2.3

In this example, the name of the branch is ``improve_install_chapter`` and the
``upstream/2.3`` value tells Git to create this branch based on the ``2.3``
branch of the ``upstream`` remote, which is the original Symfony Docs repository.

Fixes should always be based on the **oldest maintained branch** which contains
the error. Nowadays this is the ``2.3`` branch. If you are instead documenting a
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Honestly, we should store values like 2.3 in a configuration file somewhere and have a build step fill this
in dynamically (even if that process is a simple PHP script we write). That's outside of the scope, but
this is going to bite us very soon :)

new feature, switch to the first Symfony version which included it: ``2.7``,
``3.1``, etc.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

... switch to the first Symfony version that included it, e.g. upstream/3.1.

Then add:

Not sure? That's ok! Just use the upstream/master.


**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`.
:doc:`/contributing/documentation/standards`. Then, mark your contents as ready
to be committed:
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

... do your best to comply with the ...

And perhaps shorten the last sentence

Then commit your changes!


.. code-block:: bash

# if the modified content existed before
$ git commit book/installation.rst
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

missing git add before this (I suggest to use git add -p)


# if this is a new content, add it before committing it
$ git add book/new_content.rst
$ git commit book/new_content.rst

**Step 6.** **Push** the changes to your forked repository:

.. code-block:: bash

$ git commit book/installation.rst
$ git push origin improve_install_chapter

The ``origin`` value is the name of the Git remote which corresponds to your
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

that corresponds

which and that are often interchangeable, but that often sounds stronger (except in certain cases, which I consider quite rare <--- except I just used one there)

forked repository and ``improve_install_chapter`` is the name of the branch you
created previously.

**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.
Expand All @@ -97,37 +133,17 @@ which is the name of the branch you created and where you made your changes.
.. _pull-request-format:

**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:
A short phrase or paragraph describing the proposed changes is enough to ensure
that your contribution can be reviewed.

.. code-block:: text
**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.

| 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]

In this example, this table would look as follows:

.. code-block:: text

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

**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.

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:
In case you are asked to add or modify something, don't create a new pull
request. Instead, make sure that you are on the correct branch, make your
changes and push the new changes:

.. code-block:: bash

Expand All @@ -138,92 +154,27 @@ changes and push them:

$ 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, you will
get a cool `Symfony Documentation Badge`_.

Your Second Documentation Contribution
--------------------------------------

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 2.3
$ git merge upstream/2.3

This command will update the ``2.3`` branch, which is the one you used to
create the new branch for your changes. If you have used another base branch,
e.g. ``master``, replace the ``2.3`` with the appropriate branch name.

Great! Now you can proceed by following the same steps explained in the previous
section:

.. code-block:: bash

# 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 origin my_changes

# 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`_.
**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`_.

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**:
Your first contribution took some time because you had to fork the repository,
learn how to write documentation, comply with the pull requests standards, etc.
Now that you've completed your first contribution 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**:
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Check you out! You've made your first contribution to the Symfony documentation!
Somebody throw a party! Your first contribution took a little extra time because you
needed to learn a few standards and setup your computer. But now, you're dangerous.

Here is a complete checklist of steps that will guide you through your next contribution
to the Symfony docs:


.. code-block:: bash

# sync your fork with the official Symfony repository
# create a new branch based on the oldest maintained version
$ cd projects/symfony-docs/
$ git fetch upstream
$ git checkout 2.3
$ git merge upstream/2.3

# create a new branch from the oldest maintained version
$ git checkout 2.3
$ git checkout -b my_changes
$ git checkout -b my_changes upstream/2.3

# ... do your changes

Expand All @@ -233,41 +184,28 @@ steps to contribute to the Symfony documentation, which you can use as a
$ git push origin my_changes

# 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]

# (optional) make the changes requested by reviewers and commit them
$ git commit xxx.rst
$ git push

You guessed right: after all this hard work, it's **time to celebrate again!**

After completing your next contributions, you can also see how your ranking
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

also watch your ranking improve on the list...

improves in the list of `Symfony Documentation Contributors`_. You guessed
right: after all this hard work, it's **time to celebrate again!**

Review your changes
-------------------

Every GitHub Pull Request is automatically built and deployed by `Platform.sh`_
on a single environment that you can access on your browser to review your
on a single environment that you can access on your browser to review your
changes.

.. image:: /images/contributing/docs-pull-request-platformsh.png
:align: center
:alt: Platform.sh Pull Request Deployment

To access the `Platform.sh`_ environment URL, simply go to your Pull Request
page on GitHub and click on ``Details``.

.. note::

The specific configuration files at the root of the Git repository:
``.platform.app.yaml``, ``.platform/services.yaml`` and
``.platform/routes.yaml`` allow `Platform.sh`_ to build Pull Requests.
To access the `Platform.sh`_ environment URL, go to your Pull Request page on
GitHub and click on ``Details``.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Since some time you must first expand the list of tests on GitHub by clicking on the "Show all checks" text.


.. note::

Expand All @@ -278,16 +216,18 @@ 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.
frontend, it is possible to create Pull Requests right in your browser while
reading the docs on symfony.com.

First, switch to the oldest maintained Symfony branch which contains the error.
Then, click on the **edit this page** button on the upper right corner. 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 Expand Up @@ -338,11 +278,11 @@ 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/
.. _`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`: https://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
.. _`Platform.sh`: https://platform.sh
Expand Down