Skip to content

[Contributing] tweaks to the contribution chapter #4245

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 1 commit into from
Oct 2, 2014
Merged

[Contributing] tweaks to the contribution chapter #4245

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
19 changes: 5 additions & 14 deletions contributing/documentation/format.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -33,24 +33,15 @@ roles to the standard reST markup. Read more about the `Sphinx Markup Constructs
Syntax Highlighting
~~~~~~~~~~~~~~~~~~~

PHP is the default syntax highlight applied to all code blocks. You can change
it with the ``code-block`` directive:
PHP is the default syntax highlighter applied to all code blocks. You can
change it with the ``code-block`` directive:

.. code-block:: rst

.. code-block:: yaml

{ foo: bar, bar: { foo: bar, bar: baz } }

If your PHP code begins with ``<?php``, then you need to use ``html+php`` as
the name of the highlighted syntax:

.. code-block:: rst

.. code-block:: html+php

<?php echo $this->foobar(); ?>

.. note::

Besides all of the major programming languages, the syntax highlighter
Expand Down Expand Up @@ -183,7 +174,7 @@ If you're documenting a brand new feature or a change that's been made in
Symfony, you should precede your description of the change with a
``.. versionadded:: 2.X`` directive and a short description:

.. code-block:: text
.. code-block:: rst

.. versionadded:: 2.3
The ``askHiddenResponse`` method was introduced in Symfony 2.3.
Expand All @@ -193,7 +184,7 @@ Symfony, you should precede your description of the change with a
If you're documenting a behavior change, it may be helpful to *briefly* describe
how the behavior has changed.

.. code-block:: text
.. code-block:: rst

.. versionadded:: 2.3
The ``include()`` function is a new Twig feature that's available in
Expand All @@ -204,7 +195,7 @@ a new branch of the documentation is created from the ``master`` branch.
At this point, all the ``versionadded`` tags for Symfony versions that have
reached end-of-life will be removed. For example, if Symfony 2.5 were released
today, and 2.2 had recently reached its end-of-life, the 2.2 ``versionadded``
tags would be removed from the new 2.5 branch.
tags would be removed from the new ``2.5`` branch.

Testing Documentation
~~~~~~~~~~~~~~~~~~~~~
Expand Down
27 changes: 16 additions & 11 deletions contributing/documentation/overview.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,10 +3,10 @@ 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.
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's
documentation, and we are glad that you are considering joining this big family.
More than 700 developers all around the world have contributed to Symfony's
Copy link
Member

Choose a reason for hiding this comment

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

In http://symfony.com/contributors/doc you can se that there are 794 people identified as documentation contributors. Don't you think it's better to say more than 800? Otherwise, this figure will be out-dated pretty soon.

Copy link
Member Author

Choose a reason for hiding this comment

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

On https://github.com/symfony/symfony-docs, the number of contributors is 721. Do you know where the figure on symfony.com is coming from?

Copy link
Member

Choose a reason for hiding this comment

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

@xabbuh the github UI counts the number of github accounts. symfony.com counts the number of distinct email addresses. So there is 2 sources of differences:

  • people with several email addresses associated to their github account
  • people contributing with an email address not associated to their github account

@javiereguiluz why would it be outdated ? 850 is still more than 700 😄. The only way it could be outdated is when the number of contributors become lower than 700, which is not possible

Copy link
Member Author

Choose a reason for hiding this comment

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

If symfony.com counts unique e-mail addresses, the GitHub count seems more reasonable to me. For example, I used at least two different e-mail addresses in commit messages and I see no reason why this should be counted for two contributors.

Admittedly, this may look weird if people have at the contributors on symfony.com after reading this sentence. However, when you read this and then see the figure on GitHub, this seems even more weird. As @stof said, "more than 700" is true for both figures. :)

Copy link
Member

Choose a reason for hiding this comment

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

OK, let's keep the low figure.

However, GitHub is a closed source service, which means that we don't know what they really do to count contributions. This help article explains some things, such as the cases where contributions aren't counted: https://help.github.com/articles/why-are-my-contributions-not-showing-up-on-my-profile

Copy link
Member

Choose a reason for hiding this comment

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

the doc you linked talks about criteria for the contributions on the profile page. for repo contributors the rules are explained at https://help.github.com/articles/i-don-t-see-myself-in-the-repository-contributors-graph

the only case impacting us here is the case of email addresses not being linked to an account (and so ignored by github when building the list) or several addresses for the same user. The criteria about contributing to the default branch is not an issue given that other branches are merged in master regularly

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 @@ -27,9 +27,9 @@ Before Your First Contribution
Your First Documentation Contribution
-------------------------------------

In this section you'll learn how to contribute to the Symfony documentation for
In this section, you'll learn how to contribute to the Symfony documentation for
the first time. The next section will explain the shorter process you'll follow
in the future for every contribution after your first.
in the future for every contribution after your first one.

Let's imagine that you want to improve the installation chapter of the Symfony
book. In order to make your changes, follow these steps:
Expand Down Expand Up @@ -164,8 +164,12 @@ Now you can **sync your fork** by executing the following command:

$ cd projects/symfony-docs/
$ git fetch upstream
$ git checkout master
$ git merge upstream/master
$ 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 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:
Expand Down Expand Up @@ -212,8 +216,8 @@ steps to contribute to the Symfony documentation, which you can use as a
# sync your fork with the official Symfony repository
$ cd projects/symfony-docs/
$ git fetch upstream
$ git checkout master
$ git merge upstream/master
$ git checkout 2.3
$ git merge upstream/2.3

# create a new branch from the oldest maintained version
$ git checkout 2.3
Expand Down Expand Up @@ -262,10 +266,11 @@ Why Should I Use the Oldest Maintained Branch Instead of the Master Branch?

Consistent with Symfony's source code, the documentation repository is split
into multiple branches, corresponding to the different versions of Symfony itself.
The master branch holds the documentation for the development branch of the code.
The ``master`` branch holds the documentation for the development branch of
the code.

Unless you're documenting a feature that was introduced after Symfony 2.3,
your changes should always be based on the 2.3 branch. Documentation managers
your changes should always be based on the ``2.3`` branch. Documentation managers
will use the necessary Git-magic to also apply your changes to all the active
branches of the documentation.

Expand Down