8000 Revamped the documentation about "Contributing Docs" by javiereguiluz · Pull Request #4223 · symfony/symfony-docs · GitHub
[go: up one dir, main page]
Skip to content

Revamped the documentation about "Contributing Docs" #4223

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

Merged
merged 10 commits into from
Sep 16, 2014
Merged

Revamped the documentation about "Contributing Docs" #4223

Changes from 1 commit
Commits
Show all changes
10 commits
Select commit Hold shift + click to select a range
723603c
Revamped the documentation about "Contributing Docs"
javiereguiluz Sep 13, 2014
53c3a16
Added missing link
javiereguiluz Sep 13, 2014
4751eb9
lways use absolute links instead of relative for internal doc links
javiereguiluz Sep 13, 2014
79375ae
Switched another relative link into an absolute reference
javiereguiluz Sep 13, 2014
991ff6f
Added a note about not using relative internal links in the doc
javiereguiluz Sep 13, 2014
ff66e94
Added lots of fixes suggested by reviewers
javiereguiluz Sep 13, 2014
15f3c94
Added another bunch of fixes suggested by reviewers
javiereguiluz Sep 13, 2014
9bcd33d
More and more fixes and improvements
javiereguiluz Sep 13, 2014
baa06b5
Removed two highlight formats which are "experimental" and not
javiereguiluz Sep 15, 2014
88ddbb1
Fixed all the errors found by Ryan
javiereguiluz Sep 15, 2014
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
Prev Previous commit
Next Next commit
Added another bunch of fixes suggested by reviewers
  • Loading branch information
@javiereguiluz
javiereguiluz committed Sep 13, 2014
commit 15f3c94221e415845381b86b81527e11235246cc
33 changes: 16 additions & 17 deletions contributing/documentation/overview.rst
View file
Open in desktop
< 10000 td class="blob-code blob-code-context js-file-line">
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Copy link
Member

Choose a reason for hiding this comment

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

... 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
Copy link
Member

Choose a reason for hiding this comment

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

Symfony's

Expand Down Expand Up @@ -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:
Copy link
Member

Choose a reason for hiding this comment

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

In order to make your changes,


**Step 1.** Go to the official Symfony documentation repository located at
`github.com/symfony/symfony-docs <https://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
Expand Down Expand Up @@ -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
Copy link
Member

Choose a reason for hiding this comment

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

why changing this number ? The highest number in the doc repo is still far from 10000

Copy link
Member Author

Choose a reason for hiding this comment

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

I wanted to use a real looking but non-existent number.

Copy link
Member

Choose a reason for hiding this comment

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

Why shouldn't it exists? I find the previous better


**Step 9.** Now that you've successfully submitted your first contribution to the
Expand All @@ -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
--------------------------------------
Expand Down Expand Up @@ -177,7 +176,7 @@ Now you can proceed following the same steps explained in the previous section:
$ git checkout 2.3
Copy link
Member

Choose a reason for hiding this comment

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

Given that you only synchronized the master branch in the previous step, this will still use an outdated 2.3 branch

$ 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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -248,10 +247,9 @@ Frequently Asked Questions
Why Do my Changes so Long to Be Reviewed and/or Merged?
Copy link
Member

Choose a reason for hiding this comment

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

... my Changes Take so Long...

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

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?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Expand Down Expand Up @@ -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.
Copy link
Member

Choose a reason for hiding this comment

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

maybe also note that it is better to only group related changes in a PR and split the "big PR" up into several smaller PRs, to avoid conflicts.


.. _`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
Expand Down
0