diff options
author | Michael Opdenacker <michael.opdenacker@bootlin.com> | 2023-08-16 17:50:43 +0200 |
---|---|---|
committer | Richard Purdie <richard.purdie@linuxfoundation.org> | 2023-08-30 15:54:59 +0100 |
commit | 74be88d8af66558ffc7e875c16a59141e21cac7e (patch) | |
tree | 309d69476df40528070704fee0ce54159a7e5d70 | |
parent | e22eb85e9263ee2da368399e9164d7cfe75aa72a (diff) | |
download | poky-74be88d8af66558ffc7e875c16a59141e21cac7e.tar.gz |
contributor-guide: submit-changes: detail commit and patch creation
Add missing steps and try to provide better guidance and more modern
solutions, for example keeping track of the cover letter in the branch
itself.
Also add subsections to divide the instructions into easier
to understand parts.
(From yocto-docs rev: 4abe87cb20d3f023d5b0178450823d072d3321c8)
Signed-off-by: Michael Opdenacker <michael.opdenacker@bootlin.com>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
-rw-r--r-- | documentation/contributor-guide/submit-changes.rst | 148 |
1 files changed, 110 insertions, 38 deletions
diff --git a/documentation/contributor-guide/submit-changes.rst b/documentation/contributor-guide/submit-changes.rst index 533aab5b83..314b41bb63 100644 --- a/documentation/contributor-guide/submit-changes.rst +++ b/documentation/contributor-guide/submit-changes.rst | |||
@@ -140,7 +140,34 @@ The following sections provide procedures for submitting changes. | |||
140 | Preparing Changes for Submission | 140 | Preparing Changes for Submission |
141 | ================================ | 141 | ================================ |
142 | 142 | ||
143 | The first thing to do is to create a new branch in your local Git repository | 143 | Set up Git |
144 | ---------- | ||
145 | |||
146 | The first thing to do is to install Git packages. Here is an example | ||
147 | on Debian and Ubuntu:: | ||
148 | |||
149 | sudo aptitude install git-core git-email | ||
150 | |||
151 | Then, you need to set a name and e-mail address that Git will | ||
152 | use to identify your commits:: | ||
153 | |||
154 | git config --global user.name "Ada Lovelace" | ||
155 | git config --global user.email "ada.lovelace@gmail.com" | ||
156 | |||
157 | Clone the Git repository for the component to modify | ||
158 | ---------------------------------------------------- | ||
159 | |||
160 | After identifying the component to modify as described in the | ||
161 | ":doc:`../contributor-guide/identify-component`" section, clone the | ||
162 | corresponding Git repository. Here is an example for OpenEmbedded-Core:: | ||
163 | |||
164 | git clone https://git.openembedded.org/openembedded-core | ||
165 | cd openembedded-core | ||
166 | |||
167 | Create a new branch | ||
168 | ------------------- | ||
169 | |||
170 | Then, create a new branch in your local Git repository | ||
144 | for your changes, starting from the reference branch in the upstream | 171 | for your changes, starting from the reference branch in the upstream |
145 | repository (often called ``master``):: | 172 | repository (often called ``master``):: |
146 | 173 | ||
@@ -150,26 +177,37 @@ repository (often called ``master``):: | |||
150 | If you have completely unrelated sets of changes to submit, you should even | 177 | If you have completely unrelated sets of changes to submit, you should even |
151 | create one branch for each set. | 178 | create one branch for each set. |
152 | 179 | ||
153 | Then, in each branch, you should group your changes into small, controlled and | 180 | Implement and commit changes |
181 | ---------------------------- | ||
182 | |||
183 | In each branch, you should group your changes into small, controlled and | ||
154 | isolated ones. Keeping changes small and isolated aids review, makes | 184 | isolated ones. Keeping changes small and isolated aids review, makes |
155 | merging/rebasing easier and keeps the change history clean should anyone need | 185 | merging/rebasing easier and keeps the change history clean should anyone need |
156 | to refer to it in future. | 186 | to refer to it in future. |
157 | 187 | ||
158 | To this purpose, you should create *one Git commit per change*, | 188 | To this purpose, you should create *one Git commit per change*, |
159 | corresponding to each of the patches you will eventually submit. | 189 | corresponding to each of the patches you will eventually submit. |
160 | So, for each identified change: | 190 | See `further guidance <https://www.kernel.org/doc/html/latest/process/submitting-patches.html#separate-your-changes>`__ |
191 | in the Linux kernel documentation if needed. | ||
161 | 192 | ||
162 | #. *Stage Your Change:* Stage your change by using the ``git add`` | 193 | #. *Stage Your Changes:* Stage your changes by using the ``git add`` |
163 | command on each file you modified. | 194 | command on each file you modified. If you want to stage all the |
195 | files you modified, you can even use the ``git add -A`` command. | ||
164 | 196 | ||
165 | #. *Commit Your Change:* Commit the change by using the ``git commit`` | 197 | #. *Commit Your Changes:* This is when you can create separate commits. For |
166 | command. Make sure your commit information follows standards by | 198 | each commit to create, use the ``git commit -s`` command with the files |
167 | following these accepted conventions: | 199 | or directories you want to include in the commit:: |
168 | 200 | ||
169 | - Be sure to include a "Signed-off-by:" line in the same style as | 201 | $ git commit -s file1 file2 dir1 dir2 ... |
170 | required by the Linux kernel. This can be done by using the | 202 | |
171 | ``git commit -s`` command. Adding this line signifies that you, | 203 | To include **a**\ ll staged files:: |
172 | the submitter, have agreed to the `Developer's Certificate of Origin 1.1 | 204 | |
205 | $ git commit -sa | ||
206 | |||
207 | - The ``-s`` option of ``git commit`` adds a "Signed-off-by:" line | ||
208 | to your commit message. There is the same requirement for contributing | ||
209 | to the Linux kernel. Adding such a line signifies that you, the | ||
210 | submitter, have agreed to the `Developer's Certificate of Origin 1.1 | ||
173 | <https://www.kernel.org/doc/html/latest/process/submitting-patches.html#sign-your-work-the-developer-s-certificate-of-origin>`__ | 211 | <https://www.kernel.org/doc/html/latest/process/submitting-patches.html#sign-your-work-the-developer-s-certificate-of-origin>`__ |
174 | as follows: | 212 | as follows: |
175 | 213 | ||
@@ -241,39 +279,74 @@ So, for each identified change: | |||
241 | 279 | ||
242 | detailed description of change | 280 | detailed description of change |
243 | 281 | ||
244 | Using Email to Submit Patches | 282 | Creating Patches |
245 | ============================= | 283 | ================ |
246 | 284 | ||
247 | Depending on the components changed, you need to submit the email to a | 285 | Here is the general procedure on how to create patches to be sent through email: |
248 | specific mailing list. For some guidance on which mailing list to use, | 286 | |
249 | see the ":ref:`contributor-guide/submit-changes:finding a suitable mailing list`" | 287 | #. *Describe the Changes in your Branch:* If you have more than one commit |
250 | section above. | 288 | in your branch, it's recommended to provide a cover letter describing |
289 | the series of patches you are about to send. | ||
290 | |||
291 | For this purpose, a good solution is to store the cover letter contents | ||
292 | in the branch itself:: | ||
251 | 293 | ||
252 | Here is the general procedure on how to create and submit patches through email: | 294 | git branch --edit-description |
253 | 295 | ||
254 | #. *Generate Patches for your Branch:* The ``git format-patch`` command for | 296 | This will open a text editor to fill in the description for your |
297 | changes. This description can be updated when necessary and will | ||
298 | be used by Git to create the cover letter together with the patches. | ||
299 | |||
300 | It is recommended to start this description with a title line which | ||
301 | will serve a the subject line for the cover letter. | ||
302 | |||
303 | #. *Generate Patches for your Branch:* The ``git format-patch`` command will | ||
255 | generate patch files for each of the commits in your branch. You need | 304 | generate patch files for each of the commits in your branch. You need |
256 | to pass the reference branch your branch starts from:: | 305 | to pass the reference branch your branch starts from. |
306 | |||
307 | If you branch didn't need a description in the previous step:: | ||
257 | 308 | ||
258 | $ git format-patch <ref-branch> | 309 | $ git format-patch <ref-branch> |
259 | 310 | ||
260 | After the command is run, the current directory contains numbered | 311 | If you filled a description for your branch, you will want to generate |
261 | ``.patch`` files for the commits in your branch. | 312 | a cover letter too:: |
262 | 313 | ||
263 | If you have more than one patch, you should also use the ``--cover`` | 314 | $ git format-patch --cover-letter --cover-from-description=auto <ref-branch> |
264 | option with the command, which generates a cover letter as the first | ||
265 | "patch" in the series. You can then edit the cover letter to provide | ||
266 | a description for the series of patches. Run ``man git-format-patch`` | ||
267 | for details about this command. | ||
268 | 315 | ||
269 | #. *Send the patches via email:* Send the patches to the recipients and | 316 | After the command is run, the current directory contains numbered |
270 | relevant mailing lists by using the ``git send-email`` command. | 317 | ``.patch`` files for the commits in your branch. If you have a cover |
318 | letter, it will be in the ``0000-cover-letter.patch``. | ||
271 | 319 | ||
272 | .. note:: | 320 | .. note:: |
273 | 321 | ||
274 | In order to use ``git send-email``, you must have the proper Git packages | 322 | The ``--cover-from-description=auto`` option makes ``git format-patch`` |
275 | installed on your host. | 323 | use the first paragraph of the branch description as the cover |
276 | For Ubuntu, Debian, and Fedora the package is ``git-email``. | 324 | letter title. Another possibility, which is easier to remember, is to pass |
325 | only the ``--cover-letter`` option, but you will have to edit the | ||
326 | subject line manually every time you generate the patches. | ||
327 | |||
328 | See the `git format-patch manual page <https://git-scm.com/docs/git-format-patch>`__ | ||
329 | for details. | ||
330 | |||
331 | #. *Review each of the Patch Files:* This final review of the patches | ||
332 | before sending them often allows to view your changes from a different | ||
333 | perspective and discover defects such as typos, spacing issues or lines | ||
334 | or even files that you didn't intend to modify. This review should | ||
335 | include the cover letter patch too. | ||
336 | |||
337 | If necessary, rework your commits as described in | ||
338 | ":ref:`contributor-guide/submit-changes:take patch review into account`". | ||
339 | |||
340 | Sending the Patches via Email | ||
341 | ============================= | ||
342 | |||
343 | Depending on the components changed, you need to submit the email to a | ||
344 | specific mailing list. For some guidance on which mailing list to use, | ||
345 | see the ":ref:`contributor-guide/submit-changes:finding a suitable mailing list`" | ||
346 | section above. | ||
347 | |||
348 | #. *Send the patches via email:* Send the patches to the recipients and | ||
349 | relevant mailing lists by using the ``git send-email`` command. | ||
277 | 350 | ||
278 | The ``git send-email`` command sends email by using a local or remote | 351 | The ``git send-email`` command sends email by using a local or remote |
279 | Mail Transport Agent (MTA) such as ``msmtp``, ``sendmail``, or | 352 | Mail Transport Agent (MTA) such as ``msmtp``, ``sendmail``, or |
@@ -420,8 +493,8 @@ have been followed: | |||
420 | $ poky/scripts/create-pull-request -h | 493 | $ poky/scripts/create-pull-request -h |
421 | $ poky/scripts/send-pull-request -h | 494 | $ poky/scripts/send-pull-request -h |
422 | 495 | ||
423 | Responding to Patch Review | 496 | Take Patch Review into Account |
424 | ========================== | 497 | ============================== |
425 | 498 | ||
426 | You may get feedback on your submitted patches from other community members | 499 | You may get feedback on your submitted patches from other community members |
427 | or from the automated patchtest service. If issues are identified in your | 500 | or from the automated patchtest service. If issues are identified in your |
@@ -494,9 +567,8 @@ follows: | |||
494 | a newer version of the software which includes an upstream fix for the | 567 | a newer version of the software which includes an upstream fix for the |
495 | issue or when the issue has been fixed on the master branch in a way | 568 | issue or when the issue has been fixed on the master branch in a way |
496 | that introduces backwards incompatible changes. In this case follow the | 569 | that introduces backwards incompatible changes. In this case follow the |
497 | steps in ":ref:`contributor-guide/submit-changes:preparing changes for submission`" and | 570 | steps in ":ref:`contributor-guide/submit-changes:preparing changes for submission`" |
498 | ":ref:`contributor-guide/submit-changes:using email to submit patches`" | 571 | and in the following sections but modify the subject header of your patch |
499 | but modify the subject header of your patch | ||
500 | email to include the name of the stable branch which you are | 572 | email to include the name of the stable branch which you are |
501 | targetting. This can be done using the ``--subject-prefix`` argument to | 573 | targetting. This can be done using the ``--subject-prefix`` argument to |
502 | ``git format-patch``, for example to submit a patch to the dunfell | 574 | ``git format-patch``, for example to submit a patch to the dunfell |