Skip to content

Commit 870a3c1

Browse files
javiereguiluzjaviereguiluz
committed
Simplified the contribution article for Symfony Docs
1 parent fe11cd8 commit 870a3c1

File tree

1 file changed

+104
-164
lines changed

1 file changed

+104
-164
lines changed

‎contributing/documentation/overview.rst

Lines changed: 104 additions & 164 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,12 @@
11
Contributing to the Documentation
22
=================================
33

4-
One of the essential principles of the Symfony project is that **documentation is
5-
as important as code**. That's why a great amount of resources are dedicated to
6-
documenting new features and to keeping the rest of the documentation up-to-date.
4+
One of the essential principles of the Symfony project is that **documentation
5+
is as important as code**. That's why a great amount of resources are dedicated
6+
to documenting new features and to keeping the rest of the documentation up-to-
7+
date.
78

8-
More than 700 developers all around the world have contributed to Symfony's
9+
More than 1,000 developers all around the world have contributed to Symfony's
910
documentation and we are glad that you are considering joining this big family.
1011
This guide will explain everything you need to contribute to the Symfony
1112
documentation.
@@ -15,11 +16,12 @@ Before Your First Contribution
1516

1617
**Before contributing**, you should consider the following:
1718

18-
* Symfony documentation is written using reStructuredText_ markup language.
19-
If you are not familiar with this format, read :doc:`this article </contributing/documentation/format>`
20-
for a quick overview of its basic features.
21-
* Symfony documentation is hosted on GitHub_. You'll need a GitHub user account
22-
to contribute to the documentation.
19+
* Symfony documentation is written using `reStructuredText`_ markup language.
20+
If you are not familiar with this format, read :doc:`this article
21+
</contributing/documentation/format>` for a quick overview of its basic
22+
features.
23+
* Symfony documentation is hosted on `GitHub`_. You'll need a free GitHub user
24+
account to contribute to the documentation.
2325
* Symfony documentation is published under a
2426
:doc:`Creative Commons BY-SA 3.0 License </contributing/documentation/license>`
2527
and all your contributions will implicitly adhere to that license.
@@ -35,48 +37,82 @@ Let's imagine that you want to improve the installation chapter of the Symfony
3537
book. In order to make your changes, follow these steps:
3638

3739
**Step 1.** Go to the official Symfony documentation repository located at
38-
`github.com/symfony/symfony-docs`_ and `fork the repository`_ to your personal
39-
account. This is only needed the first time you contribute to Symfony.
40+
`github.com/symfony/symfony-docs`_ and click on the **Fork** button to `fork the
41+
repository`_ to your personal account. This is only needed the first time you
42+
contribute to Symfony.
4043

41-
**Step 2.** **Clone** the forked repository to your local machine (this
42-
example uses the ``projects/symfony-docs/`` directory to store the documentation;
43-
change this value accordingly):
44+
**Step 2.** **Clone** the forked repository to your local machine (this example
45+
uses the ``projects/symfony-docs/`` directory to store the documentation; change
46+
this value accordingly):
4447

4548
.. code-block:: bash
4649
4750
$ cd projects/
4851
$ git clone git://github.com/<YOUR GITHUB USERNAME>/symfony-docs.git
4952
50-
**Step 3.** Switch to the **oldest maintained branch** before making any change.
51-
Nowadays this is the ``2.3`` branch:
53+
**Step 3.** Add the original Symfony docs repository as a "Git remote" executing
54+
this command:
5255

5356
.. code-block:: bash
5457
5558
$ cd symfony-docs/
56-
$ git checkout 2.3
59+
$ git remote add upstream https://github.com/symfony/symfony-docs.git
60+
61+
If things went right, you'll see the following when listing the "remotes" of
62+
your project:
63+
64+
.. code-block:: bash
5765
58-
If you are instead documenting a new feature, switch to the first Symfony
59-
version which included it: ``2.5``, ``2.6``, etc.
66+
$ git remote -v
67+
origin https://github.com/<YOUR GITHUB USERNAME>/symfony-docs.git (fetch)
68+
origin https://github.com/<YOUR GITHUB USERNAME>/symfony-docs.git (push)
69+
upstream https://github.com/symfony/symfony-docs.git (fetch)
70+
upstream https://github.com/symfony/symfony-docs.git (push)
6071
61-
**Step 4.** Create a dedicated **new branch** for your changes. This greatly
62-
simplifies the work of reviewing and merging your changes. Use a short and
63-
memorable name for the new branch:
72+
The purpose of this step is to allow you work simultaneously on the official
73+
Symfony repository and on your own fork. You'll see this in action in a moment.
74+
75+
**Step 4.** Create a dedicated **new branch** for your changes. Use a short and
76+
memorable name for the new branch (if you are fixing a reported issue, use
77+
``fix_XXX`` as the branch name, where ``XXX`` is the number of the issue):
6478

6579
.. code-block:: bash
6680
67-
$ git checkout -b improve_install_chapter
81+
$ git checkout -b improve_install_chapter upstream/2.3
82+
83+
In this example, the name of the branch is ``improve_install_chapter`` and the
84+
``upstream/2.3`` value tells Git to create this branch based on the ``2.3``
85+
branch of the ``upstream`` remote, which is the original Symfony Docs repository.
86+
87+
Fixes should always be based on the **oldest maintained branch** which contains
88+
the error. Nowadays this is the ``2.3`` branch. If you are instead documenting a
89+
new feature, switch to the first Symfony version which included it: ``2.7``,
90+
``3.1``, etc.
6891

6992
**Step 5.** Now make your changes in the documentation. Add, tweak, reword and
7093
even remove any content, but make sure that you comply with the
71-
:doc:`/contributing/documentation/standards`.
94+
:doc:`/contributing/documentation/standards`. Then, mark your contents as ready
95+
to be committed:
96+
97+
.. code-block:: bash
98+
99+
# if the modified content existed before
100+
$ git commit book/installation.rst
101+
102+
# if this is a new content, add it before committing it
103+
$ git add book/new_content.rst
104+
$ git commit book/new_content.rst
72105
73106
**Step 6.** **Push** the changes to your forked repository:
74107

75108
.. code-block:: bash
76109
77-
$ git commit book/installation.rst
78110
$ git push origin improve_install_chapter
79111
112+
The ``origin`` value is the name of the Git remote which corresponds to your
113+
forked repository and ``improve_install_chapter`` is the name of the branch you
114+
created previously.
115+
80116
**Step 7.** Everything is now ready to initiate a **pull request**. Go to your
81117
forked repository at ``https//github.com/<YOUR GITHUB USERNAME>/symfony-docs``
82118
and click on the **Pull Requests** link located in the sidebar.
@@ -97,37 +133,17 @@ which is the name of the branch you created and where you made your changes.
97133
.. _pull-request-format:
98134

99135
**Step 8.** The last step is to prepare the **description** of the pull request.
100-
To ensure that your work is reviewed quickly, please add the following table
101-
at the beginning of your pull request description:
136+
A short phrase or paragraph describing the proposed changes is enough to ensure
137+
that your contribution can be reviewed.
102138

103-
.. code-block:: text
139+
**Step 9.** Now that you've successfully submitted your first contribution to
140+
the Symfony documentation, **go and celebrate!** The documentation managers
141+
will carefully review your work in short time and they will let you know about
142+
any required change.
104143

105-
| Q | A
106-
| ------------- | ---
107-
| Doc fix? | [yes|no]
108-
| New docs? | [yes|no] (PR # on symfony/symfony if applicable)
109-
| Applies to | [Symfony version numbers this applies to]
110-
| Fixed tickets | [comma separated list of tickets fixed by the PR]
111-
112-
In this example, this table would look as follows:
113-
114-
.. code-block:: text
115-
116-
| Q | A
117-
| ------------- | ---
118-
| Doc fix? | yes
119-
| New docs? | no
120-
| Applies to | all
121-
| Fixed tickets | #10575
122-
123-
**Step 9.** Now that you've successfully submitted your first contribution to the
124-
Symfony documentation, **go and celebrate!** The documentation managers will
125-
carefully review your work in short time and they will let you know about any
126-
required change.
127-
128-
In case you need to add or modify anything, there is no need to create a new
129-
pull request. Just make sure that you are on the correct branch, make your
130-
changes and push them:
144+
In case you are asked to add or modify something, don't create a new pull
145+
request. Instead, make sure that you are on the correct branch, make your
146+
changes and push the new changes:
131147

132148
.. code-block:: bash
133149
@@ -138,92 +154,27 @@ changes and push them:
138154
139155
$ git push
140156
141-
**Step 10.** After your pull request is eventually accepted and merged in the Symfony
142-
documentation, you will be included in the `Symfony Documentation Contributors`_
143-
list. Moreover, if you happen to have a SensioLabsConnect_ profile, you will
144-
get a cool `Symfony Documentation Badge`_.
145-
146-
Your Second Documentation Contribution
147-
--------------------------------------
148-
149-
The first contribution took some time because you had to fork the repository,
150-
learn how to write documentation, comply with the pull requests standards, etc.
151-
The second contribution will be much easier, except for one detail: given the
152-
furious update activity of the Symfony documentation repository, odds are that
153-
your fork is now out of date with the official repository.
154-
155-
Solving this problem requires you to `sync your fork`_ with the original repository.
156-
To do this, execute this command first to tell git about the original repository:
157-
158-
.. code-block:: bash
159-
160-
$ cd projects/symfony-docs/
161-
$ git remote add upstream https://github.com/symfony/symfony-docs.git
162-
163-
Now you can **sync your fork** by executing the following command:
164-
165-
.. code-block:: bash
166-
167-
$ cd projects/symfony-docs/
168-
$ git fetch upstream
169-
$ git checkout 2.3
170-
$ git merge upstream/2.3
171-
172-
This command will update the ``2.3`` branch, which is the one you used to
173-
create the new branch for your changes. If you have used another base branch,
174-
e.g. ``master``, replace the ``2.3`` with the appropriate branch name.
175-
176-
Great! Now you can proceed by following the same steps explained in the previous
177-
section:
178-
179-
.. code-block:: bash
180-
181-
# create a new branch to store your changes based on the 2.3 branch
182-
$ cd projects/symfony-docs/
183-
$ git checkout 2.3
184-
$ git checkout -b my_changes
185-
186-
# ... do your changes
187-
188-
# submit the changes to your forked repository
189-
$ git add xxx.rst # (optional) only if this is a new content
190-
$ git commit xxx.rst
191-
$ git push origin my_changes
192-
193-
# go to GitHub and create the Pull Request
194-
#
195-
# Include this table in the description:
196-
# | Q | A
197-
# | ------------- | ---
198-
# | Doc fix? | [yes|no]
199-
# | New docs? | [yes|no] (PR # on symfony/symfony if applicable)
200-
# | Applies to | [Symfony version numbers this applies to]
201-
# | Fixed tickets | [comma separated list of tickets fixed by the PR]
202-
203-
Your second contribution is now complete, so **go and celebrate again!**
204-
You can also see how your ranking improves in the list of
205-
`Symfony Documentation Contributors`_.
157+
**Step 10.** After your pull request is eventually accepted and merged in the
158+
Symfony documentation, you will be included in the `Symfony Documentation
159+
Contributors`_ list. Moreover, if you happen to have a `SensioLabsConnect`_
160+
profile, you will get a cool `Symfony Documentation Badge`_.
206161

207162
Your Next Documentation Contributions
208163
-------------------------------------
209164

210-
Now that you've made two contributions to the Symfony documentation, you are
211-
probably comfortable with all the Git-magic involved in the process. That's
212-
why your next contributions would be much faster. Here you can find the complete
213-
steps to contribute to the Symfony documentation, which you can use as a
214-
**checklist**:
165+
Your first contribution took some time because you had to fork the repository,
166+
learn how to write documentation, comply with the pull requests standards, etc.
167+
Now that you've completed your first contribution to the Symfony documentation,
168+
you are probably comfortable with all the Git-magic involved in the process.
169+
That's why your next contributions would be much faster. Here you can find the
170+
complete steps to contribute to the Symfony documentation, which you can use as
171+
a **checklist**:
215172

216173
.. code-block:: bash
217174
218-
# sync your fork with the official Symfony repository
175+
# create a new branch based on the oldest maintained version
219176
$ cd projects/symfony-docs/
220-
$ git fetch upstream
221-
$ git checkout 2.3
222-
$ git merge upstream/2.3
223-
224-
# create a new branch from the oldest maintained version
225-
$ git checkout 2.3
226-
$ git checkout -b my_changes
177+
$ git checkout -b my_changes upstream/2.3
227178
228179
# ... do your changes
229180
@@ -233,41 +184,28 @@ steps to contribute to the Symfony documentation, which you can use as a
233184
$ git push origin my_changes
234185
235186
# go to GitHub and create the Pull Request
236-
#
237-
# Include this table in the description:
238-
# | Q | A
239-
# | ------------- | ---
240-
# | Doc fix? | [yes|no]
241-
# | New docs? | [yes|no] (PR # on symfony/symfony if applicable)
242-
# | Applies to | [Symfony version numbers this applies to]
243-
# | Fixed tickets | [comma separated list of tickets fixed by the PR]
244187
245188
# (optional) make the changes requested by reviewers and commit them
246189
$ git commit xxx.rst
247190
$ git push
248191
249-
You guessed right: after all this hard work, it's **time to celebrate again!**
250-
192+
After completing your next contributions, you can also see how your ranking
193+
improves in the list of `Symfony Documentation Contributors`_. You guessed
194+
right: after all this hard work, it's **time to celebrate again!**
251195

252196
Review your changes
253197
-------------------
254198

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

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

263-
To access the `Platform.sh`_ environment URL, simply go to your Pull Request
264-
page on GitHub and click on ``Details``.
265-
266-
.. note::
267-
268-
The specific configuration files at the root of the Git repository:
269-
``.platform.app.yaml``, ``.platform/services.yaml`` and
270-
``.platform/routes.yaml`` allow `Platform.sh`_ to build Pull Requests.
207+
To access the `Platform.sh`_ environment URL, go to your Pull Request page on
208+
GitHub and click on ``Details``.
271209

272210
.. note::
273211

@@ -278,16 +216,18 @@ Minor Changes (e.g. Typos)
278216
--------------------------
279217

280218
You may find just a typo and want to fix it. Due to GitHub's functional
281-
frontend, it is quite simple to create Pull Requests right in your
282-
browser while reading the docs on symfony.com. To do this, just click
283-
the **edit this page** button on the upper right corner. Beforehand,
284-
please switch to the right branch as mentioned before. Now you are able
285-
to edit the content and describe your changes within the GitHub
286-
frontend. When your work is done, click **Propose file change** to
287-
create a commit and, in case it is your first contribution, also your
288-
fork. A new branch is created automatically in order to provide a base
289-
for your Pull Request. Then fill out the form to create the Pull Request
290-
as described above.
219+
frontend, it is possible to create Pull Requests right in your browser while
220+
reading the docs on symfony.com.
221+
222+
First, switch to the oldest maintained Symfony branch which contains the error.
223+
Then, click on the **edit this page** button on the upper right corner. Now you
224+
are able to edit the content and describe your changes within the GitHub
225+
frontend.
226+
227+
When your work is done, click **Propose file change** to create a commit and, in
228+
case it is your first contribution, also your fork. A new branch is created
229+
automatically in order to provide a base for your Pull Request. Then fill out
230+
the form to create the Pull Request as described above.
291231

292232
Frequently Asked Questions
293233
--------------------------
@@ -338,11 +278,11 @@ your proposal after you put all that hard work into making the changes. We
338278
definitely don't want you to waste your time!
339279

340280
.. _`github.com/symfony/symfony-docs`: https://github.com/symfony/symfony-docs
341-
.. _reStructuredText: http://docutils.sourceforge.net/rst.html
342-
.. _GitHub: https://github.com/
281+
.. _`reStructuredText`: http://docutils.sourceforge.net/rst.html
282+
.. _`GitHub`: https://github.com/
343283
.. _`fork the repository`: https://help.github.com/articles/fork-a-repo
344284
.. _`Symfony Documentation Contributors`: https://symfony.com/contributors/doc
345-
.. _SensioLabsConnect: https://connect.sensiolabs.com/
285+
.. _`SensioLabsConnect`: https://connect.sensiolabs.com/
346286
.. _`Symfony Documentation Badge`: https://connect.sensiolabs.com/badge/36/symfony-documentation-contributor
347287
.. _`sync your fork`: https://help.github.com/articles/syncing-a-fork
348288
.. _`Platform.sh`: https://platform.sh

0 commit comments

Comments
 (0)