1- Submitting aPatch
1+ Proposing aChange
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
1021Install the Software Stack
@@ -90,20 +101,27 @@ Check that the current Tests Pass
90101Now that Symfony is installed, check that all unit tests pass for your
91102environment 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
96115The 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 must know that all the code you are going to submit
119+ must be released under the *MIT license *.
102120
103121Choose the right Branch
104122~~~~~~~~~~~~~~~~~~~~~~~
105123
106- Before working on apatch , you must determine on which branch you need to
124+ Before working on aPR , you must determine on which branch you need to
107125work:
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 apatch
120- for the ``3.4 `` branch, thepatch will also be applied by the core team on
137+ recent branches on a regular basis. For instance, if you submit aPR
138+ for the ``3.4 `` branch, thePR will also be applied by the core team on
121139 the ``master `` branch.
122140
123141Create a Topic Branch
124142~~~~~~~~~~~~~~~~~~~~~
125143
126- Each time you want to work on apatch for a bug or on an enhancement, create a
144+ Each time you want to work on aPR for a bug or on an enhancement, create a
127145topic branch:
128146
129147..code-block ::terminal
130148
131149 $ git checkout -b BRANCH_NAME master
132150
133- bugfix for the ``3.4 `` branch, first track the remote
151+ 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- 3.4 `` branch to work on thebugfix :
158+ 3.4 `` branch to work on thebug 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.
167185link `` command, be sure that the dependencies of the project you
168186want 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
173193Work on the code as much as you want and commit as much as you want; but keep
174194in 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 yourpatch is not about a bug fix (when you add a new feature or change
238+ When yourPR is not about a bug fix (when you add a new feature or change
217239an 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 yourpatch is ready for submission, follow the
253+ Whenever you feel that yourPR is ready for submission, follow the
230254following 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
236262while to finish your changes):
237263
238264..code-block ::terminal
@@ -246,7 +272,7 @@ while to finish your changes):
246272tip ::
247273
248274 Replace ``master `` with the branch you selected previously (e.g. ``3.4 ``)
249- if you are working on abugfix
275+ if you are working on abug fix.
250276
251277When 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 abugfix based on the ``3.4 `` branch.
302+ the core team to pull abug fix based on the ``3.4 `` branch.
277303
278304To ease the core team work, always include the modified components in your
279305pull 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?", thepatch must contain updates to the
325+ * If you answer yes to "BC breaks?", thePR must contain updates to the
300326 relevant ``CHANGELOG `` and ``UPGRADE `` files;
301327
302- * If you answer yes to "Deprecations?", thepatch must contain updates to the
328+ * If you answer yes to "Deprecations?", thePR 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
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
331358In the pull request description, give as much details as possible about your
332359changes (don't hesitate to give code examples to illustrate your points). If
@@ -339,11 +366,29 @@ commit message).
339366In addition to this "code" pull request, you must also send a pull request to
340367the `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, once again please join 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
345390Based on the feedback on the pull request, you might need to rework your
346- patch . Before re-submitting thepatch , rebase with ``upstream/master `` or
391+ PR . Before re-submitting thePR , 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