Skip to content

Commit d4b5e77

Browse files
webmozartweaverryan
authored andcommitted
Added initial draft of "Community Reviews" page
1 parent 79775ae commit d4b5e77

File tree

2 files changed

+190
-0
lines changed

2 files changed

+190
-0
lines changed

contributing/community/index.rst

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,4 +5,5 @@ Community
55
:maxdepth: 2
66

77
releases
8+
reviews
89
other

contributing/community/reviews.rst

Lines changed: 189 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,189 @@
1+
Community Reviews
2+
=================
3+
4+
Symfony is an open-source project driven by a large community. If you don't feel
5+
ready to contribute code or patches, reviewing issues and pull requests (PRs)
6+
can be a great start to get involved and give back.
7+
8+
Why Reviewing is Important
9+
--------------------------
10+
11+
Community reviews are essential for the development of the Symfony framework,
12+
since there are many more pull requests and bug reports than there are members
13+
in the Symfony core team to review, fix and merge them.
14+
15+
On the `Symfony issue tracker`_, you can find many items in a "Needs review"
16+
status:
17+
18+
* **Bug Reports**: Bug reports primarily need to be checked for completeness.
19+
Is any important information missing? Can the bug easily be reproduced?
20+
21+
* **Pull Requests**: Pull requests contain code that fixes a bug or implements
22+
new functionality. Reviews of pull requests ensure that they are implemented
23+
properly, are covered by test cases, don't introduce new bugs and maintain
24+
backwards compatibility.
25+
26+
Note that **anyone who has some basic familiarity with Symfony and PHP can
27+
review bug reports and pull requests**. You don't need to be an expert to help.
28+
29+
Be Constructive
30+
---------------
31+
32+
Before you begin, remember that you are looking at the result of someone else's
33+
hard work. A good review post thanks the contributor for their work, identifies
34+
what was done well, identifies what should be improved, and suggests a next
35+
step.
36+
37+
Create a GitHub Account
38+
-----------------------
39+
40+
Symfony uses GitHub_ to manage bug reports and pull requests. If you want to
41+
do reviews, you need to `create a GitHub account`_ and log in.
42+
43+
The Bug Report Review Process
44+
-----------------------------
45+
46+
A good way to get started with reviewing is to pick a bug report from the
47+
`bug reports in need of review queue`_.
48+
49+
The steps for the review are:
50+
51+
1. **Is the Report Complete?**
52+
53+
Good bug reports contain a link to a fork of the `Symfony Standard Edition`_
54+
(the "reproduction project") that reproduces the bug. If it doesn't, the
55+
report should at least contain enough information and code samples to
56+
reproduce the bug.
57+
58+
2. **Reproduce the Bug**
59+
60+
Download the reproduction project and test whether the bug can be reproduced
61+
on your system. If the reporter did not provide a reproduction project,
62+
create one by forking_ the `Symfony Standard Edition`_. Reproduce the bug
63+
with the instructions given by the reporter.
64+
65+
3. **Update the Issue Status**
66+
67+
At last, add a comment and update the status of the bug report. **Thank the
68+
reporter for reporting the bug**. Include the line ``Status: <status>`` in
69+
your comment to update the status to one of the following:
70+
71+
**Needs Work** If the bug does not contain enough information to be
72+
reproduced, explain what information is missing and move the report to this
73+
status.
74+
75+
**Works for me** If the bug *does* contain enough information to be
76+
reproduced but works on your system, or if the reported bug is a feature and
77+
not a bug, provide a short explanation and move the report to this status.
78+
79+
**Reviewed** If you can reproduce the bug, move the report to this status.
80+
If you created a reproduction project, include the link to the project in
81+
your comment.
82+
83+
.. topic:: Example
84+
85+
Here is a sample comment for a bug report that could be reproduced:
86+
87+
.. code-block:: text
88+
89+
Thank you @weaverryan for creating this bug report! This indeed looks
90+
like a bug. I reproduced the bug in the "kernel-bug" branch of
91+
https://github.com/webmozart/symfony-standard.
92+
93+
Status: Reviewed
94+
95+
The Pull Request Review Process
96+
-------------------------------
97+
98+
The process for reviewing pull requests (PRs) is similar to doing a review of a
99+
bug report. Reviews of pull requests usually take a little longer since you need
100+
to understand the functionality that has been fixed or implemented and then find
101+
out whether the implementation is complete.
102+
103+
It is okay to do partial reviews. If you do a partial review, post how far you
104+
got and leave the PR in "Needs Review" state.
105+
106+
The steps for the review are:
107+
108+
1. **Is the PR Complete**?
109+
110+
Every pull request must contain a header that gives some basic information
111+
about the PR. You can find the template for that header in the
112+
`Contribution Guidelines`_.
113+
114+
2. **Is the Base Branch Correct?**
115+
116+
GitHub displays the branch that a PR is based on below the title of the
117+
pull request. Is that branch correct?
118+
119+
* Bugs should be fixed in the oldest, maintained version that contains the
120+
bug. Check `Symfony's Release Schedule`_ to find the oldest currently
121+
supported version.
122+
123+
* New features should always be added to the current development version.
124+
Check the `Symfony Roadmap`_ to find the current development version.
125+
126+
2. **Reproduce the Problem**
127+
128+
Read the issue that the pull request is supposed to fix. Reproduce the
129+
problem on a clean `Symfony Standard Edition`_ project and try to understand
130+
why it exists.
131+
132+
3. **Review the Code**
133+
134+
Read the code of the pull request and check it against some common criteria:
135+
136+
* Does the code address the issue the PR is intended to fix/add?
137+
* Does the PR stay within scope to address *only* that issue?
138+
* Does the PR contain automated tests? Do those tests cover all relevant
139+
edge cases?
140+
* Does the PR contain sufficient comments to easily understand its code?
141+
* Does the code break backwards compatibility? If yes, does the PR header say
142+
so?
143+
* Does the PR contain deprecations? If yes, does the PR header say so? Does
144+
the code contain ``trigger_error()`` statements for all deprecated
145+
features?
146+
* Are all deprecations and backwards compatibility breaks documented in the
147+
latest UPGRADE-X.X.md file? Do those explanations contain "Before"/"After"
148+
with a clear upgrade path?
149+
150+
4. **Test the Code**
151+
152+
Take your project from step 2 and test whether the PR works properly.
153+
154+
TODO: precise steps
155+
156+
5. **Update the PR Status**
157+
158+
At last, add a comment and update the status of the PR. **Thank the
159+
contributor for working on the PR**. Include the line ``Status: <status>`` in
160+
your comment to update the status to one of the following:
161+
162+
**Needs Work** If the PR is not yet ready to be merged, explain the issues
163+
that you found and move it to this status.
164+
165+
**Reviewed** If the PR satisfies all the checks above, move it to this
166+
status. A core contributor will soon look at the PR and decide whether it can
167+
be merged or needs further work.
168+
169+
.. topic:: Example
170+
171+
Here is a sample comment for a PR that is not yet ready for merge:
172+
173+
.. code-block:: text
174+
175+
Thank you @weaverryan for working on this feature! It seems that test
176+
cases are missing for the cases that the counter is zero or smaller.
177+
Could you add them please?
178+
179+
Status: Needs Work
180+
181+
.. _GitHub: https://github.com
182+
.. _Symfony issue tracker: https://github.com/symfony/symfony/issues
183+
.. _Symfony Standard Edition: https://github.com/symfony/symfony-standard
184+
.. _create a GitHub account: https://help.github.com/articles/signing-up-for-a-new-github-account/
185+
.. _forking: https://help.github.com/articles/fork-a-repo/
186+
.. _bug reports in need of review queue: https://github.com/symfony/symfony/issues?utf8=%E2%9C%93&q=is%3Aopen+is%3Aissue+label%3A%22Bug%22+label%3A%22Status%3A+Needs+Review%22+
187+
.. _Contribution Guidelines: https://github.com/symfony/symfony/blob/master/CONTRIBUTING.md
188+
.. _Symfony's Release Schedule: http://symfony.com/doc/current/contributing/community/releases.html#schedule
189+
.. _Symfony Roadmap: https://symfony.com/roadmap

0 commit comments

Comments
 (0)