Integrated PR comments

Author: webmozart

contributing/code/patches.rst

@@ -247,6 +247,8 @@ Check that all tests still pass and push your branch remotely:
 
     $ git push --force origin BRANCH_NAME
 
+.. _contributing-code-pull-request:
+
 Make a Pull Request
 ~~~~~~~~~~~~~~~~~~~
 

contributing/community/reviews.rst

@@ -5,7 +5,7 @@ Symfony is an open-source project driven by a large community. If you don't feel
 ready to contribute code or patches, reviewing issues and pull requests (PRs)
 can be a great start to get involved and give back.
 
-Why Reviewing is Important
+Why Reviewing Is Important
 --------------------------
 
 Community reviews are essential for the development of the Symfony framework,
@@ -16,7 +16,7 @@ On the `Symfony issue tracker`_, you can find many items in a "Needs Review"
 status:
 
 * **Bug Reports**: Bug reports primarily need to be checked for completeness.
-  Is any important information missing? Can the bug easily be reproduced?
+  Is any important information missing? Can the bug be easily reproduced?
 
 * **Pull Requests**: Pull requests contain code that fixes a bug or implements
   new functionality. Reviews of pull requests ensure that they are implemented
@@ -30,9 +30,9 @@ Be Constructive
 ---------------
 
 Before you begin, remember that you are looking at the result of someone else's
-hard work. A good review post thanks the contributor for their work, identifies
-what was done well, identifies what should be improved, and suggests a next
-step.
+hard work. A good review comment thanks the contributor for their work,
+identifies what was done well, identifies what should be improved and suggests a
+next step.
 
 Create a GitHub Account
 -----------------------
@@ -48,25 +48,27 @@ A good way to get started with reviewing is to pick a bug report from the
 
 The steps for the review are:
 
-1. **Is the Report Complete?**
+#. **Is the Report Complete?**
 
    Good bug reports contain a link to a fork of the `Symfony Standard Edition`_
    (the "reproduction project") that reproduces the bug. If it doesn't, the
    report should at least contain enough information and code samples to
    reproduce the bug.
 
-2. **Reproduce the Bug**
+#. **Reproduce the Bug**
 
    Download the reproduction project and test whether the bug can be reproduced
    on your system. If the reporter did not provide a reproduction project,
    create one by forking_ the `Symfony Standard Edition`_. Reproduce the bug
    with the instructions given by the reporter.
 
-3. **Update the Issue Status**
+#. **Update the Issue Status**
 
-   At last, add a comment and update the status of the bug report. **Thank the
-   reporter for reporting the bug**. Include the line ``Status: <status>`` in
-   your comment to update the status to one of the following:
+   At last, add a comment to the bug report. **Thank the reporter for reporting
+   the bug**. Include the line ``Status: <status>`` in your comment to update
+   the status of the ticket. This line will trigger our `Carson Bot`_ which
+   updates the labels of the issue accordingly. You can set the status to one of
+   the following:
 
    **Needs Work** If the bug does not contain enough information to be
    reproduced, explain what information is missing and move the report to this
@@ -100,36 +102,36 @@ bug report. Reviews of pull requests usually take a little longer since you need
 to understand the functionality that has been fixed or implemented and then find
 out whether the implementation is complete.
 
-It is okay to do partial reviews. If you do a partial review, post how far you
-got and leave the PR in "Needs Review" state.
+It is okay to do partial reviews. If you do a partial review, comment how far
+you got and leave the PR in "Needs Review" state.
 
 Pick a pull request from the `PRs in need of review`_ and follow these steps:
 
-1. **Is the PR Complete**?
+#. **Is the PR Complete**?
 
    Every pull request must contain a header that gives some basic information
    about the PR. You can find the template for that header in the
-   `Contribution Guidelines`_.
+   :ref:`Contribution Guidelines <contributing-code-pull-request>`.
 
-2. **Is the Base Branch Correct?**
+#. **Is the Base Branch Correct?**
 
    GitHub displays the branch that a PR is based on below the title of the
    pull request. Is that branch correct?
 
    * Bugs should be fixed in the oldest, maintained version that contains the
-     bug. Check `Symfony's Release Schedule`_ to find the oldest currently
-     supported version.
+     bug. Check :doc:`Symfony's Release Schedule <releases>` to find the oldest
+     currently supported version.
 
    * New features should always be added to the current development version.
      Check the `Symfony Roadmap`_ to find the current development version.
 
-3. **Reproduce the Problem**
+#. **Reproduce the Problem**
 
    Read the issue that the pull request is supposed to fix. Reproduce the
    problem on a clean `Symfony Standard Edition`_ project and try to understand
    why it exists.
 
-4. **Review the Code**
+#. **Review the Code**
 
    Read the code of the pull request and check it against some common criteria:
 
@@ -145,19 +147,23 @@ Pick a pull request from the `PRs in need of review`_ and follow these steps:
      features?
    * Are all deprecations and backwards compatibility breaks documented in the
      latest UPGRADE-X.X.md file? Do those explanations contain "Before"/"After"
-     with a clear upgrade path?
+     examples with clear upgrade instructions?
 
-5. **Test the Code**
+   Eventually, some of these aspects will be checked automatically.
 
-   Take your project from step 2 and test whether the PR works properly.
+#. **Test the Code**
+
+   Take your project from step 3 and test whether the PR works properly.
 
    TODO: precise steps
 
-6. **Update the PR Status**
+#. **Update the PR Status**
 
-   At last, add a comment and update the status of the PR. **Thank the
-   contributor for working on the PR**. Include the line ``Status: <status>`` in
-   your comment to update the status to one of the following:
+   At last, add a comment to the PR. **Thank the contributor for working on the
+   PR**. Include the line ``Status: <status>`` in your comment to update the
+   status of the ticket. This line will trigger our `Carson Bot`_ which updates
+   the labels of the issue accordingly. You can set the status to one of the
+   following:
 
    **Needs Work** If the PR is not yet ready to be merged, explain the issues
    that you found and move it to this status.
@@ -174,7 +180,7 @@ Pick a pull request from the `PRs in need of review`_ and follow these steps:
 
         Thank you @weaverryan for working on this! It seems that your test
         cases don't cover the cases when the counter is zero or smaller.
-        Could you add some tests for that?
+        Could you please add some tests for that?
 
         Status: Needs Work
 
@@ -188,3 +194,4 @@ Pick a pull request from the `PRs in need of review`_ and follow these steps:
 .. _Contribution Guidelines: https://github.com/symfony/symfony/blob/master/CONTRIBUTING.md
 .. _Symfony's Release Schedule: http://symfony.com/doc/current/contributing/community/releases.html#schedule
 .. _Symfony Roadmap: https://symfony.com/roadmap
+.. _Carson Bot: https://github.com/carsonbot/carsonbot