8000 Added hints about receiving feedback · symfony/symfony-docs@e47dae0 · GitHub
[go: up one dir, main page]
Skip to content

Commit e47dae0

Browse files
lsmith77lsmith77
committed
Added hints about receiving feedback
1 parent 98dfd5d commit e47dae0
<
8000
/div>

File tree

4 files changed

+87
-37
lines changed

4 files changed

+87
-37
lines changed

‎_build/redirection_map

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -413,3 +413,4 @@
413413
/session/sessions_directory /session
414414
/frontend/encore/legacy-apps /frontend/encore/legacy-applications
415415
/configuration/external_parameters /configuration/environment_variables
416+
/contributing/code/patches /contributing/code/pull_requests

‎contributing/code/index.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@ Contributing Code
66

77
bugs
88
reproducer
9-
patches
9+
pull_requests
1010
maintenance
1111
core_team
1212
security

‎contributing/code/patches.rst renamed to ‎contributing/code/pull_requests.rst

Lines changed: 84 additions & 35 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,21 @@
1-
Submitting a Patch
1+
Proposing a Change
22
==================
33

4-
Patches are the best way to provide a bug fix or to propose enhancements to
5-
Symfony.
4+
A pull request, "PR" for short, is the best way to provide a bug fix or to
5+
propose enhancements to Symfony.
66

7-
Step 1: Setup your Environment
7+
Step 1: Check existing Issues and Pull Requests
8+
-----------------------------------------------
9+
10+
Before working on a change, check to see if someone else also raised the topic
11+
or maybe even started working on a PR by `searching on GitHub`_.
12+
13+
If you are unsure or if you have any questions during this entire process,
14+
please ask your questions on the #contribs channel on `Symfony Slack`_.
15+
16+
.. _step-1-setup-your-environment:
17+
18+
Step 2: Setup your Environment
819
------------------------------
920

1021
Install the Software Stack
@@ -90,20 +101,27 @@ Check that the current Tests Pass
90101
Now that Symfony is installed, check that all unit tests pass for your
91102
environment as explained in the dedicated :doc:`document <tests>`.
92103

93-
Step 2: Work on your Patch
94-
--------------------------
104+
.. tip::
105+
106+
If tests are failing, check on `Travis-CI`_ if the same test is
107+
failing there as well. In that case you do not need to be concerned
108+
about the test failing locally.
109+
110+
.. _step-2-work-on-your-patch:
111+
112+
Step 3: Work on your Pull Request
113+
---------------------------------
95114

96115
The License
97116
~~~~~~~~~~~
98117

99-
Before you start, you must know that all the patches you are going to submit
100-
must be released under the *MIT license*, unless explicitly specified in your
101-
commits.
118+
Before you start, you should be aware that all the code you are going to submit
119+
must be released under the *MIT license*.
102120

103121
Choose the right Branch
104122
~~~~~~~~~~~~~~~~~~~~~~~
105123

106-
Before working on a patch, you must determine on which branch you need to
124+
Before working on a PR, you must determine on which branch you need to
107125
work:
108126

109127
* ``3.4``, if you are fixing a bug for an existing feature or want to make a
@@ -116,28 +134,28 @@ work:
116134
.. note::
117135

118136
All bug fixes merged into maintenance branches are also merged into more
119-
recent branches on a regular basis. For instance, if you submit a patch
120-
for the ``3.4`` branch, the patch will also be applied by the core team on
137+
recent branches on a regular basis. For instance, if you submit a PR
138+
for the ``3.4`` branch, the PR will also be applied by the core team on
121139
the ``master`` branch.
122140

123141
Create a Topic Branch
124142
~~~~~~~~~~~~~~~~~~~~~
125143

126-
Each time you want to work on a patch for a bug or on an enhancement, create a
144+
Each time you want to work on a PR for a bug or on an enhancement, create a
127145
topic branch:
128146

129147
.. code-block:: terminal
130148
131149
$ git checkout -b BRANCH_NAME master
132150
133-
Or, if you want to provide a bugfix for the ``3.4`` branch, first track the remote
151+
Or, if you want to provide a bug fix for the ``3.4`` branch, first track the remote
134152
``3.4`` branch locally:
135153

136154
.. code-block:: terminal
137155
138156
$ git checkout -t origin/3.4
139157
140-
Then create a new branch off the ``3.4`` branch to work on the bugfix:
158+
Then create a new branch off the ``3.4`` branch to work on the bug fix:
141159

142160
.. code-block:: terminal
143161
@@ -167,8 +185,10 @@ uses, and replaces them by symbolic links to the ones in the Git repository.
167185
Before running the ``link`` command, be sure that the dependencies of the project you
168186
want to debug are installed by running ``composer install`` inside it.
169187

170-
Work on your Patch
171-
~~~~~~~~~~~~~~~~~~
188+
.. _work-on-your-patch:
189+
190+
Work on your Pull Request
191+
~~~~~~~~~~~~~~~~~~~~~~~~~
172192

173193
Work on the code as much as you want and commit as much as you want; but keep
174194
in mind the following:
@@ -181,7 +201,7 @@ in mind the following:
181201
actually works;
182202

183203
* Try hard to not break backward compatibility (if you must do so, try to
184-
provide a compatibility layer to support the old way) -- patches that break
204+
provide a compatibility layer to support the old way) -- PRs that break
185205
backward compatibility have less chance to be merged;
186206

187207
* Do atomic and logically separate commits (use the power of ``git rebase`` to
@@ -210,10 +230,12 @@ in mind the following:
210230
verb (``fixed ...``, ``added ...``, ...) to start the summary and don't
211231
add a period at the end.
212232

213-
Prepare your Patch for Submission
214-
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
233+
.. _prepare-your-patch-for-submission:
234+
235+
Prepare your Pull Request for Submission
236+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
215237

216-
When your patch is not about a bug fix (when you add a new feature or change
238+
When your PR is not about a bug fix (when you add a new feature or change
217239
an existing one for instance), it must also include the following:
218240

219241
* An explanation of the changes in the relevant ``CHANGELOG`` file(s) (the
@@ -223,16 +245,20 @@ an existing one for instance), it must also include the following:
223245
``UPGRADE`` file(s) if the changes break backward compatibility or if you
224246
deprecate something that will ultimately break backward compatibility.
225247

226-
Step 3: Submit your Patch
227-
-------------------------
248+
.. _step-4-submit-your-patch:
249+
250+
Step 4: Submit your Pull Request
251+
--------------------------------
228252

229-
Whenever you feel that your patch is ready for submission, follow the
253+
Whenever you feel that your PR is ready for submission, follow the
230254
following steps.
231255

232-
Rebase your Patch
233-
~~~~~~~~~~~~~~~~~
256+
.. _rebase-your-patch:
234257

235-
Before submitting your patch, update your branch (needed if it takes you a
258+
Rebase your Pull Request
259+
~~~~~~~~~~~~~~~~~~~~~~~~
260+
261+
Before submitting your PR, update your branch (needed if it takes you a
236262
while to finish your changes):
237263

238264
.. code-block:: terminal
@@ -246,7 +272,7 @@ while to finish your changes):
246272
.. tip::
247273

248274
Replace ``master`` with the branch you selected previously (e.g. ``3.4``)
249-
if you are working on a bugfix
275+
if you are working on a bug fix.
250276

251277
When doing the ``rebase`` command, you might have to fix merge conflicts.
252278
``git status`` will show you the *unmerged* files. Resolve all the conflicts,
@@ -273,7 +299,7 @@ You can now make a pull request on the ``symfony/symfony`` GitHub repository.
273299
.. tip::
274300

275301
Take care to point your pull request towards ``symfony:3.4`` if you want
276-
the core team to pull a bugfix based on the ``3.4`` branch.
302+
the core team to pull a bug fix based on the ``3.4`` branch.
277303

278304
To ease the core team work, always include the modified components in your
279305
pull request message, like in:
@@ -296,10 +322,10 @@ Some answers to the questions trigger some more requirements:
296322
* If you answer yes to "New feature?", you must submit a pull request to the
297323
documentation and reference it under the "Doc PR" section;
298324

299-
* If you answer yes to "BC breaks?", the patch must contain updates to the
10000 325+
* If you answer yes to "BC breaks?", the PR must contain updates to the
300326
relevant ``CHANGELOG`` and ``UPGRADE`` files;
301327

302-
* If you answer yes to "Deprecations?", the patch must contain updates to the
328+
* If you answer yes to "Deprecations?", the PR must contain updates to the
303329
relevant ``CHANGELOG`` and ``UPGRADE`` files;
304330

305331
* If you answer no to "Tests pass", you must add an item to a todo-list with
@@ -326,7 +352,8 @@ because you want early feedback on your work, add an item to todo-list:
326352
- [ ] gather feedback for my changes
327353
328354
As long as you have items in the todo-list, please prefix the pull request
329-
title with "[WIP]".
355+
title with "[WIP]". If you do not yet want to trigger the automated tests,
356+
you can also set the PR to `draft status`_.
330357

331358
In the pull request description, give as much details as possible about your
332359
changes (don't hesitate to give code examples to illustrate your points). If
@@ -339,11 +366,29 @@ commit message).
339366
In addition to this "code" pull request, you must also send a pull request to
340367
the `documentation repository`_ to update the documentation when appropriate.
341368

342-
Rework your Patch
343-
~~~~~~~~~~~~~~~~~
369+
Step 5: Receiving Feedback
370+
--------------------------
371+
372+
We ask all contributors to follow some
373+
:doc:`best practices </contributing/community/reviews>`
374+
to ensure a constructive feedback process.
375+
376+
If you think someone fails to keep this advice in mind and you want another
377+
perspective, please join the #contribs channel on `Symfony Slack`_. If you
378+
receive feedback you find abusive please contact the
379+
:doc:`CARE team</contributing/code_of_conduct/care_team.rst>`.
380+
381+
The :doc:`core team <contributing/code/core_team>` is responsible for deciding
382+
which PR gets merged, so their feedback is the most relevant. So do not feel
383+
pressured to refactor your code immediately when someone provides feedback.
384+
385+
.. _rework-your-patch:
386+
387+
Rework your Pull Request
388+
~~~~~~~~~~~~~~~~~~~~~~~~
344389

345390
Based on the feedback on the pull request, you might need to rework your
346-
patch. Before re-submitting the patch, rebase with ``upstream/master`` or
391+
PR. Before re-submitting the PR, rebase with ``upstream/master`` or
347392
``upstream/3.4``, don't merge; and force the push to the origin:
348393

349394
.. code-block:: terminal
@@ -374,3 +419,7 @@ before merging.
374419
.. _`fabbot`: https://fabbot.io
375420
.. _`PSR-1`: https://www.php-fig.org/psr/psr-1/
376421
.. _`PSR-2`: https://www.php-fig.org/psr/psr-2/
422+
.. _`searching on GitHub`: https://github.com/symfony/symfony/issues?q=+is%3Aopen+
423+
.. _`Symfony Slack`: https://symfony.com/slack-invite
424+
.. _`Travis-CI`: https://travis-ci.org/symfony/symfony
425+
.. _`draft status`: https://help.github.com/en/articles/about-pull-requests#draft-pull-requests

‎contributing/map.rst.inc

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,7 @@
88
* **Code**
99

1010
* :doc:`Bugs </contributing/code/bugs>`
11-
* :doc:`Patc 4DB4 hes </contributing/code/patches>`
11+
* :doc:`Patches </contributing/code/pull_requests>`
1212
* :doc:`Reviewing Issues and Patches </contributing/community/reviews>`
1313
* :doc:`Maintenance </contributing/code/maintenance>`
1414
* :doc:`The Core Team </contributing/code/core_team>`

0 commit comments

Comments
 (0)
0