diff options
| author | Scott Rifenbark <srifenbark@gmail.com> | 2018-05-17 09:32:22 -0700 |
|---|---|---|
| committer | Richard Purdie <richard.purdie@linuxfoundation.org> | 2018-05-24 17:16:36 +0100 |
| commit | 368474d7409fd5ae8f8cf8aa08dd0c4d14a4f575 (patch) | |
| tree | d7b6082870b06c154e1b02a898acc93a21af5e81 /documentation/dev-manual/dev-manual-newbie.xml | |
| parent | 9a37a3d568a04319cece45edfa04e787e06c4399 (diff) | |
| download | poky-368474d7409fd5ae8f8cf8aa08dd0c4d14a4f575.tar.gz | |
dev-manual: Removed "newbie" chapter.
This chapter only had the stuff about submitting a defect against
YP and making a change to YP. I moved that information into the
common tasks chapter as it is "how-to" information. Removal of this
chapter alse required that the mega-manual.xml file be updated to
not include the chapter.
(From yocto-docs rev: 4421b1585c21a6f7862525ba972f7e765626066e)
Signed-off-by: Scott Rifenbark <srifenbark@gmail.com>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
Diffstat (limited to 'documentation/dev-manual/dev-manual-newbie.xml')
| -rw-r--r-- | documentation/dev-manual/dev-manual-newbie.xml | 627 |
1 files changed, 0 insertions, 627 deletions
diff --git a/documentation/dev-manual/dev-manual-newbie.xml b/documentation/dev-manual/dev-manual-newbie.xml deleted file mode 100644 index 27e1d04761..0000000000 --- a/documentation/dev-manual/dev-manual-newbie.xml +++ /dev/null | |||
| @@ -1,627 +0,0 @@ | |||
| 1 | <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" | ||
| 2 | "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" | ||
| 3 | [<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] > | ||
| 4 | |||
| 5 | <chapter id='dev-manual-newbie'> | ||
| 6 | |||
| 7 | <title>The Yocto Project Open Source Development Environment</title> | ||
| 8 | |||
| 9 | <section id='submitting-a-defect-against-the-yocto-project'> | ||
| 10 | <title>Submitting a Defect Against the Yocto Project</title> | ||
| 11 | |||
| 12 | <para> | ||
| 13 | Use the Yocto Project implementation of | ||
| 14 | <ulink url='http://www.bugzilla.org/about/'>Bugzilla</ulink> | ||
| 15 | to submit a defect (bug) against the Yocto Project. | ||
| 16 | For additional information on this implementation of Bugzilla see the | ||
| 17 | "<ulink url='&YOCTO_DOCS_REF_URL;#resources-bugtracker'>Yocto Project Bugzilla</ulink>" | ||
| 18 | section in the Yocto Project Reference Manual. | ||
| 19 | For more detail on any of the following steps, see the Yocto Project | ||
| 20 | <ulink url='&YOCTO_WIKI_URL;/wiki/Bugzilla_Configuration_and_Bug_Tracking'>Bugzilla wiki page</ulink>. | ||
| 21 | </para> | ||
| 22 | |||
| 23 | <para> | ||
| 24 | Use the following general steps to submit a bug" | ||
| 25 | |||
| 26 | <orderedlist> | ||
| 27 | <listitem><para> | ||
| 28 | Open the Yocto Project implementation of | ||
| 29 | <ulink url='&YOCTO_BUGZILLA_URL;'>Bugzilla</ulink>. | ||
| 30 | </para></listitem> | ||
| 31 | <listitem><para> | ||
| 32 | Click "File a Bug" to enter a new bug. | ||
| 33 | </para></listitem> | ||
| 34 | <listitem><para> | ||
| 35 | Choose the appropriate "Classification", "Product", and | ||
| 36 | "Component" for which the bug was found. | ||
| 37 | Bugs for the Yocto Project fall into one of several | ||
| 38 | classifications, which in turn break down into several | ||
| 39 | products and components. | ||
| 40 | For example, for a bug against the | ||
| 41 | <filename>meta-intel</filename> layer, you would choose | ||
| 42 | "Build System, Metadata & Runtime", "BSPs", and | ||
| 43 | "bsps-meta-intel", respectively. | ||
| 44 | </para></listitem> | ||
| 45 | <listitem><para> | ||
| 46 | Choose the "Version" of the Yocto Project for which you found | ||
| 47 | the bug (e.g. &DISTRO;). | ||
| 48 | </para></listitem> | ||
| 49 | <listitem><para> | ||
| 50 | Determine and select the "Severity" of the bug. | ||
| 51 | The severity indicates how the bug impacted your work. | ||
| 52 | </para></listitem> | ||
| 53 | <listitem><para> | ||
| 54 | Choose the "Hardware" that the bug impacts. | ||
| 55 | </para></listitem> | ||
| 56 | <listitem><para> | ||
| 57 | Choose the "Architecture" that the bug impacts. | ||
| 58 | </para></listitem> | ||
| 59 | <listitem><para> | ||
| 60 | Choose a "Documentation change" item for the bug. | ||
| 61 | Fixing a bug might or might not affect the Yocto Project | ||
| 62 | documentation. | ||
| 63 | If you are unsure of the impact to the documentation, select | ||
| 64 | "Don't Know". | ||
| 65 | </para></listitem> | ||
| 66 | <listitem><para> | ||
| 67 | Provide a brief "Summary" of the bug. | ||
| 68 | Try to limit your summary to just a line or two and be sure | ||
| 69 | to capture the essence of the bug. | ||
| 70 | </para></listitem> | ||
| 71 | <listitem><para> | ||
| 72 | Provide a detailed "Description" of the bug. | ||
| 73 | You should provide as much detail as you can about the context, | ||
| 74 | behavior, output, and so forth that surrounds the bug. | ||
| 75 | You can even attach supporting files for output from logs by | ||
| 76 | using the "Add an attachment" button. | ||
| 77 | </para></listitem> | ||
| 78 | <listitem><para> | ||
| 79 | Click the "Submit Bug" button submit the bug. | ||
| 80 | A new Bugzilla number is assigned to the bug and the defect | ||
| 81 | is logged in the bug tracking system. | ||
| 82 | </para></listitem> | ||
| 83 | </orderedlist> | ||
| 84 | Once you file a bug, the bug is processed by the Yocto Project Bug | ||
| 85 | Triage Team and further details concerning the bug are assigned | ||
| 86 | (e.g. priority and owner). | ||
| 87 | You are the "Submitter" of the bug and any further categorization, | ||
| 88 | progress, or comments on the bug result in Bugzilla sending you an | ||
| 89 | automated email concerning the particular change or progress to the | ||
| 90 | bug. | ||
| 91 | </para> | ||
| 92 | </section> | ||
| 93 | |||
| 94 | <section id='how-to-submit-a-change'> | ||
| 95 | <title>Submitting a Change to the Yocto Project</title> | ||
| 96 | |||
| 97 | <para> | ||
| 98 | Contributions to the Yocto Project and OpenEmbedded are very welcome. | ||
| 99 | Because the system is extremely configurable and flexible, we recognize | ||
| 100 | that developers will want to extend, configure or optimize it for | ||
| 101 | their specific uses. | ||
| 102 | </para> | ||
| 103 | |||
| 104 | <para> | ||
| 105 | The Yocto Project uses a mailing list and a patch-based workflow | ||
| 106 | that is similar to the Linux kernel but contains important | ||
| 107 | differences. | ||
| 108 | In general, a mailing list exists through which you can submit | ||
| 109 | patches. | ||
| 110 | You should send patches to the appropriate mailing list so that they | ||
| 111 | can be reviewed and merged by the appropriate maintainer. | ||
| 112 | The specific mailing list you need to use depends on the | ||
| 113 | location of the code you are changing. | ||
| 114 | Each component (e.g. layer) should have a | ||
| 115 | <filename>README</filename> file that indicates where to send | ||
| 116 | the changes and which process to follow. | ||
| 117 | </para> | ||
| 118 | |||
| 119 | <para> | ||
| 120 | You can send the patch to the mailing list using whichever approach | ||
| 121 | you feel comfortable with to generate the patch. | ||
| 122 | Once sent, the patch is usually reviewed by the community at large. | ||
| 123 | If somebody has concerns with the patch, they will usually voice | ||
| 124 | their concern over the mailing list. | ||
| 125 | If a patch does not receive any negative reviews, the maintainer of | ||
| 126 | the affected layer typically takes the patch, tests it, and then | ||
| 127 | based on successful testing, merges the patch. | ||
| 128 | </para> | ||
| 129 | |||
| 130 | <para id='figuring-out-the-mailing-list-to-use'> | ||
| 131 | The "poky" repository, which is the Yocto Project's reference build | ||
| 132 | environment, is a hybrid repository that contains several | ||
| 133 | individual pieces (e.g. BitBake, Metadata, documentation, | ||
| 134 | and so forth) built using the combo-layer tool. | ||
| 135 | The upstream location used for submitting changes varies by | ||
| 136 | component: | ||
| 137 | <itemizedlist> | ||
| 138 | <listitem><para> | ||
| 139 | <emphasis>Core Metadata:</emphasis> | ||
| 140 | Send your patch to the | ||
| 141 | <ulink url='http://lists.openembedded.org/mailman/listinfo/openembedded-core'>openembedded-core</ulink> | ||
| 142 | mailing list. For example, a change to anything under | ||
| 143 | the <filename>meta</filename> or | ||
| 144 | <filename>scripts</filename> directories should be sent | ||
| 145 | to this mailing list. | ||
| 146 | </para></listitem> | ||
| 147 | <listitem><para> | ||
| 148 | <emphasis>BitBake:</emphasis> | ||
| 149 | For changes to BitBake (i.e. anything under the | ||
| 150 | <filename>bitbake</filename> directory), send your patch | ||
| 151 | to the | ||
| 152 | <ulink url='http://lists.openembedded.org/mailman/listinfo/bitbake-devel'>bitbake-devel</ulink> | ||
| 153 | mailing list. | ||
| 154 | </para></listitem> | ||
| 155 | <listitem><para> | ||
| 156 | <emphasis>"meta-*" trees:</emphasis> | ||
| 157 | These trees contain Metadata. | ||
| 158 | Use the | ||
| 159 | <ulink url='https://lists.yoctoproject.org/listinfo/poky'>poky</ulink> | ||
| 160 | mailing list. | ||
| 161 | </para></listitem> | ||
| 162 | </itemizedlist> | ||
| 163 | </para> | ||
| 164 | |||
| 165 | <para> | ||
| 166 | For changes to other layers hosted in the Yocto Project source | ||
| 167 | repositories (i.e. <filename>yoctoproject.org</filename>), tools, | ||
| 168 | and the Yocto Project documentation, use the | ||
| 169 | <ulink url='https://lists.yoctoproject.org/listinfo/yocto'>Yocto Project</ulink> | ||
| 170 | general mailing list. | ||
| 171 | <note> | ||
| 172 | Sometimes a layer's documentation specifies to use a | ||
| 173 | particular mailing list. | ||
| 174 | If so, use that list. | ||
| 175 | </note> | ||
| 176 | For additional recipes that do not fit into the core Metadata, you | ||
| 177 | should determine which layer the recipe should go into and submit | ||
| 178 | the change in the manner recommended by the documentation (e.g. | ||
| 179 | the <filename>README</filename> file) supplied with the layer. | ||
| 180 | If in doubt, please ask on the Yocto general mailing list or on | ||
| 181 | the openembedded-devel mailing list. | ||
| 182 | </para> | ||
| 183 | |||
| 184 | <para> | ||
| 185 | You can also push a change upstream and request a maintainer to | ||
| 186 | pull the change into the component's upstream repository. | ||
| 187 | You do this by pushing to a contribution repository that is upstream. | ||
| 188 | See the | ||
| 189 | "<ulink url='&YOCTO_DOCS_OM_URL;#gs-git-workflows-and-the-yocto-project'>Git Workflows and the Yocto Project</ulink>" | ||
| 190 | section in the Yocto Project Overview and Concepts Manual for additional | ||
| 191 | concepts on working in the Yocto Project development environment. | ||
| 192 | </para> | ||
| 193 | |||
| 194 | <para> | ||
| 195 | Two commonly used testing repositories exist for | ||
| 196 | OpenEmbedded-Core: | ||
| 197 | <itemizedlist> | ||
| 198 | <listitem><para> | ||
| 199 | <emphasis>"ross/mut" branch:</emphasis> | ||
| 200 | The "mut" (master-under-test) tree | ||
| 201 | exists in the <filename>poky-contrib</filename> repository | ||
| 202 | in the | ||
| 203 | <ulink url='&YOCTO_GIT_URL;'>Yocto Project source repositories</ulink>. | ||
| 204 | </para></listitem> | ||
| 205 | <listitem><para> | ||
| 206 | <emphasis>"master-next" branch:</emphasis> | ||
| 207 | This branch is part of the main | ||
| 208 | "poky" repository in the Yocto Project source repositories. | ||
| 209 | </para></listitem> | ||
| 210 | </itemizedlist> | ||
| 211 | Maintainers use these branches to test submissions prior to merging | ||
| 212 | patches. | ||
| 213 | Thus, you can get an idea of the status of a patch based on | ||
| 214 | whether the patch has been merged into one of these branches. | ||
| 215 | <note> | ||
| 216 | This system is imperfect and changes can sometimes get lost in the | ||
| 217 | flow. | ||
| 218 | Asking about the status of a patch or change is reasonable if the | ||
| 219 | change has been idle for a while with no feedback. | ||
| 220 | The Yocto Project does have plans to use | ||
| 221 | <ulink url='https://en.wikipedia.org/wiki/Patchwork_(software)'>Patchwork</ulink> | ||
| 222 | to track the status of patches and also to automatically preview | ||
| 223 | patches. | ||
| 224 | </note> | ||
| 225 | </para> | ||
| 226 | |||
| 227 | <para> | ||
| 228 | The following sections provide procedures for submitting a change. | ||
| 229 | </para> | ||
| 230 | |||
| 231 | <section id='pushing-a-change-upstream'> | ||
| 232 | <title>Using Scripts to Push a Change Upstream and Request a Pull</title> | ||
| 233 | |||
| 234 | <para> | ||
| 235 | Follow this procedure to push a change to an upstream "contrib" | ||
| 236 | Git repository: | ||
| 237 | <note> | ||
| 238 | You can find general Git information on how to push a change | ||
| 239 | upstream in the | ||
| 240 | <ulink url='http://git-scm.com/book/en/v2/Distributed-Git-Distributed-Workflows'>Git Community Book</ulink>. | ||
| 241 | </note> | ||
| 242 | <orderedlist> | ||
| 243 | <listitem><para> | ||
| 244 | <emphasis>Make Your Changes Locally:</emphasis> | ||
| 245 | Make your changes in your local Git repository. | ||
| 246 | You should make small, controlled, isolated changes. | ||
| 247 | Keeping changes small and isolated aids review, | ||
| 248 | makes merging/rebasing easier and keeps the change | ||
| 249 | history clean should anyone need to refer to it in | ||
| 250 | future. | ||
| 251 | </para></listitem> | ||
| 252 | <listitem><para> | ||
| 253 | <emphasis>Stage Your Changes:</emphasis> | ||
| 254 | Stage your changes by using the <filename>git add</filename> | ||
| 255 | command on each file you changed. | ||
| 256 | </para></listitem> | ||
| 257 | <listitem><para id='making-sure-you-have-correct-commit-information'> | ||
| 258 | <emphasis>Commit Your Changes:</emphasis> | ||
| 259 | Commit the change by using the | ||
| 260 | <filename>git commit</filename> command. | ||
| 261 | Make sure your commit information follows standards by | ||
| 262 | following these accepted conventions: | ||
| 263 | <itemizedlist> | ||
| 264 | <listitem><para> | ||
| 265 | Be sure to include a "Signed-off-by:" line in the | ||
| 266 | same style as required by the Linux kernel. | ||
| 267 | Adding this line signifies that you, the submitter, | ||
| 268 | have agreed to the Developer's Certificate of | ||
| 269 | Origin 1.1 as follows: | ||
| 270 | <literallayout class='monospaced'> | ||
| 271 | Developer's Certificate of Origin 1.1 | ||
| 272 | |||
| 273 | By making a contribution to this project, I certify that: | ||
| 274 | |||
| 275 | (a) The contribution was created in whole or in part by me and I | ||
| 276 | have the right to submit it under the open source license | ||
| 277 | indicated in the file; or | ||
| 278 | |||
| 279 | (b) The contribution is based upon previous work that, to the best | ||
| 280 | of my knowledge, is covered under an appropriate open source | ||
| 281 | license and I have the right under that license to submit that | ||
| 282 | work with modifications, whether created in whole or in part | ||
| 283 | by me, under the same open source license (unless I am | ||
| 284 | permitted to submit under a different license), as indicated | ||
| 285 | in the file; or | ||
| 286 | |||
| 287 | (c) The contribution was provided directly to me by some other | ||
| 288 | person who certified (a), (b) or (c) and I have not modified | ||
| 289 | it. | ||
| 290 | |||
| 291 | (d) I understand and agree that this project and the contribution | ||
| 292 | are public and that a record of the contribution (including all | ||
| 293 | personal information I submit with it, including my sign-off) is | ||
| 294 | maintained indefinitely and may be redistributed consistent with | ||
| 295 | this project or the open source license(s) involved. | ||
| 296 | </literallayout> | ||
| 297 | </para></listitem> | ||
| 298 | <listitem><para> | ||
| 299 | Provide a single-line summary of the change. | ||
| 300 | and, | ||
| 301 | if more explanation is needed, provide more | ||
| 302 | detail in the body of the commit. | ||
| 303 | This summary is typically viewable in the | ||
| 304 | "shortlist" of changes. | ||
| 305 | Thus, providing something short and descriptive | ||
| 306 | that gives the reader a summary of the change is | ||
| 307 | useful when viewing a list of many commits. | ||
| 308 | You should prefix this short description with the | ||
| 309 | recipe name (if changing a recipe), or else with | ||
| 310 | the short form path to the file being changed. | ||
| 311 | </para></listitem> | ||
| 312 | <listitem><para> | ||
| 313 | For the body of the commit message, provide | ||
| 314 | detailed information that describes what you | ||
| 315 | changed, why you made the change, and the approach | ||
| 316 | you used. | ||
| 317 | It might also be helpful if you mention how you | ||
| 318 | tested the change. | ||
| 319 | Provide as much detail as you can in the body of | ||
| 320 | the commit message. | ||
| 321 | <note> | ||
| 322 | You do not need to provide a more detailed | ||
| 323 | explanation of a change if the change is | ||
| 324 | minor to the point of the single line | ||
| 325 | summary providing all the information. | ||
| 326 | </note> | ||
| 327 | </para></listitem> | ||
| 328 | <listitem><para> | ||
| 329 | If the change addresses a specific bug or issue | ||
| 330 | that is associated with a bug-tracking ID, | ||
| 331 | include a reference to that ID in your detailed | ||
| 332 | description. | ||
| 333 | For example, the Yocto Project uses a specific | ||
| 334 | convention for bug references - any commit that | ||
| 335 | addresses a specific bug should use the following | ||
| 336 | form for the detailed description. | ||
| 337 | Be sure to use the actual bug-tracking ID from | ||
| 338 | Bugzilla for | ||
| 339 | <replaceable>bug-id</replaceable>: | ||
| 340 | <literallayout class='monospaced'> | ||
| 341 | Fixes [YOCTO #<replaceable>bug-id</replaceable>] | ||
| 342 | |||
| 343 | <replaceable>detailed description of change</replaceable> | ||
| 344 | </literallayout> | ||
| 345 | </para></listitem> | ||
| 346 | </itemizedlist> | ||
| 347 | </para></listitem> | ||
| 348 | <listitem><para> | ||
| 349 | <emphasis>Push Your Commits to a "Contrib" Upstream:</emphasis> | ||
| 350 | If you have arranged for permissions to push to an | ||
| 351 | upstream contrib repository, push the change to that | ||
| 352 | repository: | ||
| 353 | <literallayout class='monospaced'> | ||
| 354 | $ git push <replaceable>upstream_remote_repo</replaceable> <replaceable>local_branch_name</replaceable> | ||
| 355 | </literallayout> | ||
| 356 | For example, suppose you have permissions to push into the | ||
| 357 | upstream <filename>meta-intel-contrib</filename> | ||
| 358 | repository and you are working in a local branch named | ||
| 359 | <replaceable>your_name</replaceable><filename>/README</filename>. | ||
| 360 | The following command pushes your local commits to the | ||
| 361 | <filename>meta-intel-contrib</filename> upstream | ||
| 362 | repository and puts the commit in a branch named | ||
| 363 | <replaceable>your_name</replaceable><filename>/README</filename>: | ||
| 364 | <literallayout class='monospaced'> | ||
| 365 | $ git push meta-intel-contrib <replaceable>your_name</replaceable>/README | ||
| 366 | </literallayout> | ||
| 367 | </para></listitem> | ||
| 368 | <listitem><para id='push-determine-who-to-notify'> | ||
| 369 | <emphasis>Determine Who to Notify:</emphasis> | ||
| 370 | Determine the maintainer or the mailing list | ||
| 371 | that you need to notify for the change.</para> | ||
| 372 | |||
| 373 | <para>Before submitting any change, you need to be sure | ||
| 374 | who the maintainer is or what mailing list that you need | ||
| 375 | to notify. | ||
| 376 | Use either these methods to find out: | ||
| 377 | <itemizedlist> | ||
| 378 | <listitem><para> | ||
| 379 | <emphasis>Maintenance File:</emphasis> | ||
| 380 | Examine the <filename>maintainers.inc</filename> | ||
| 381 | file, which is located in the | ||
| 382 | <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink> | ||
| 383 | at | ||
| 384 | <filename>meta/conf/distro/include</filename>, | ||
| 385 | to see who is responsible for code. | ||
| 386 | </para></listitem> | ||
| 387 | <listitem><para> | ||
| 388 | <emphasis>Search by File:</emphasis> | ||
| 389 | Using <ulink url='&YOCTO_DOCS_OM_URL;#git'>Git</ulink>, | ||
| 390 | you can enter the following command to bring up a | ||
| 391 | short list of all commits against a specific file: | ||
| 392 | <literallayout class='monospaced'> | ||
| 393 | git shortlog -- <replaceable>filename</replaceable> | ||
| 394 | </literallayout> | ||
| 395 | Just provide the name of the file for which you | ||
| 396 | are interested. | ||
| 397 | The information returned is not ordered by history | ||
| 398 | but does include a list of everyone who has | ||
| 399 | committed grouped by name. | ||
| 400 | From the list, you can see who is responsible for | ||
| 401 | the bulk of the changes against the file. | ||
| 402 | </para></listitem> | ||
| 403 | <listitem><para> | ||
| 404 | <emphasis>Examine the List of Mailing Lists:</emphasis> | ||
| 405 | For a list of the Yocto Project and related mailing | ||
| 406 | lists, see the | ||
| 407 | "<ulink url='&YOCTO_DOCS_REF_URL;#resources-mailinglist'>Mailing lists</ulink>" | ||
| 408 | section in the Yocto Project Reference Manual. | ||
| 409 | </para></listitem> | ||
| 410 | </itemizedlist> | ||
| 411 | </para></listitem> | ||
| 412 | <listitem><para> | ||
| 413 | <emphasis>Make a Pull Request:</emphasis> | ||
| 414 | Notify the maintainer or the mailing list that you have | ||
| 415 | pushed a change by making a pull request.</para> | ||
| 416 | |||
| 417 | <para>The Yocto Project provides two scripts that | ||
| 418 | conveniently let you generate and send pull requests to the | ||
| 419 | Yocto Project. | ||
| 420 | These scripts are <filename>create-pull-request</filename> | ||
| 421 | and <filename>send-pull-request</filename>. | ||
| 422 | You can find these scripts in the | ||
| 423 | <filename>scripts</filename> directory within the | ||
| 424 | <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink> | ||
| 425 | (e.g. <filename>~/poky/scripts</filename>). | ||
| 426 | </para> | ||
| 427 | |||
| 428 | <para>Using these scripts correctly formats the requests | ||
| 429 | without introducing any whitespace or HTML formatting. | ||
| 430 | The maintainer that receives your patches either directly | ||
| 431 | or through the mailing list needs to be able to save and | ||
| 432 | apply them directly from your emails. | ||
| 433 | Using these scripts is the preferred method for sending | ||
| 434 | patches.</para> | ||
| 435 | |||
| 436 | <para>First, create the pull request. | ||
| 437 | For example, the following command runs the script, | ||
| 438 | specifies the upstream repository in the contrib directory | ||
| 439 | into which you pushed the change, and provides a subject | ||
| 440 | line in the created patch files: | ||
| 441 | <literallayout class='monospaced'> | ||
| 442 | $ ~/poky/scripts/create-pull-request -u meta-intel-contrib -s "Updated Manual Section Reference in README" | ||
| 443 | </literallayout> | ||
| 444 | Running this script forms | ||
| 445 | <filename>*.patch</filename> files in a folder named | ||
| 446 | <filename>pull-</filename><replaceable>PID</replaceable> | ||
| 447 | in the current directory. | ||
| 448 | One of the patch files is a cover letter.</para> | ||
| 449 | |||
| 450 | <para>Before running the | ||
| 451 | <filename>send-pull-request</filename> script, you must | ||
| 452 | edit the cover letter patch to insert information about | ||
| 453 | your change. | ||
| 454 | After editing the cover letter, send the pull request. | ||
| 455 | For example, the following command runs the script and | ||
| 456 | specifies the patch directory and email address. | ||
| 457 | In this example, the email address is a mailing list: | ||
| 458 | <literallayout class='monospaced'> | ||
| 459 | $ ~/poky/scripts/send-pull-request -p ~/meta-intel/pull-10565 -t meta-intel@yoctoproject.org | ||
| 460 | </literallayout> | ||
| 461 | You need to follow the prompts as the script is | ||
| 462 | interactive. | ||
| 463 | <note> | ||
| 464 | For help on using these scripts, simply provide the | ||
| 465 | <filename>-h</filename> argument as follows: | ||
| 466 | <literallayout class='monospaced'> | ||
| 467 | $ poky/scripts/create-pull-request -h | ||
| 468 | $ poky/scripts/send-pull-request -h | ||
| 469 | </literallayout> | ||
| 470 | </note> | ||
| 471 | </para></listitem> | ||
| 472 | </orderedlist> | ||
| 473 | </para> | ||
| 474 | </section> | ||
| 475 | |||
| 476 | <section id='submitting-a-patch'> | ||
| 477 | <title>Using Email to Submit a Patch</title> | ||
| 478 | |||
| 479 | <para> | ||
| 480 | You can submit patches without using the | ||
| 481 | <filename>create-pull-request</filename> and | ||
| 482 | <filename>send-pull-request</filename> scripts described in the | ||
| 483 | previous section. | ||
| 484 | However, keep in mind, the preferred method is to use the scripts. | ||
| 485 | </para> | ||
| 486 | |||
| 487 | <para> | ||
| 488 | Depending on the components changed, you need to submit the email | ||
| 489 | to a specific mailing list. | ||
| 490 | For some guidance on which mailing list to use, see the | ||
| 491 | <link linkend='figuring-out-the-mailing-list-to-use'>list</link> | ||
| 492 | at the beginning of this section. | ||
| 493 | For a description of all the available mailing lists, see the | ||
| 494 | "<ulink url='&YOCTO_DOCS_REF_URL;#resources-mailinglist'>Mailing Lists</ulink>" | ||
| 495 | section in the Yocto Project Reference Manual. | ||
| 496 | </para> | ||
| 497 | |||
| 498 | <para> | ||
| 499 | Here is the general procedure on how to submit a patch through | ||
| 500 | email without using the scripts: | ||
| 501 | <orderedlist> | ||
| 502 | <listitem><para> | ||
| 503 | <emphasis>Make Your Changes Locally:</emphasis> | ||
| 504 | Make your changes in your local Git repository. | ||
| 505 | You should make small, controlled, isolated changes. | ||
| 506 | Keeping changes small and isolated aids review, | ||
| 507 | makes merging/rebasing easier and keeps the change | ||
| 508 | history clean should anyone need to refer to it in | ||
| 509 | future. | ||
| 510 | </para></listitem> | ||
| 511 | <listitem><para> | ||
| 512 | <emphasis>Stage Your Changes:</emphasis> | ||
| 513 | Stage your changes by using the <filename>git add</filename> | ||
| 514 | command on each file you changed. | ||
| 515 | </para></listitem> | ||
| 516 | <listitem><para> | ||
| 517 | <emphasis>Commit Your Changes:</emphasis> | ||
| 518 | Commit the change by using the | ||
| 519 | <filename>git commit --signoff</filename> command. | ||
| 520 | Using the <filename>--signoff</filename> option identifies | ||
| 521 | you as the person making the change and also satisfies | ||
| 522 | the Developer's Certificate of Origin (DCO) shown earlier. | ||
| 523 | </para> | ||
| 524 | |||
| 525 | <para>When you form a commit, you must follow certain | ||
| 526 | standards established by the Yocto Project development | ||
| 527 | team. | ||
| 528 | See | ||
| 529 | <link linkend='making-sure-you-have-correct-commit-information'>Step 3</link> | ||
| 530 | in the previous section for information on how to | ||
| 531 | provide commit information that meets Yocto Project | ||
| 532 | commit message standards. | ||
| 533 | </para></listitem> | ||
| 534 | <listitem><para> | ||
| 535 | <emphasis>Format the Commit:</emphasis> | ||
| 536 | Format the commit into an email message. | ||
| 537 | To format commits, use the | ||
| 538 | <filename>git format-patch</filename> command. | ||
| 539 | When you provide the command, you must include a revision | ||
| 540 | list or a number of patches as part of the command. | ||
| 541 | For example, either of these two commands takes your most | ||
| 542 | recent single commit and formats it as an email message in | ||
| 543 | the current directory: | ||
| 544 | <literallayout class='monospaced'> | ||
| 545 | $ git format-patch -1 | ||
| 546 | </literallayout> | ||
| 547 | or | ||
| 548 | <literallayout class='monospaced'> | ||
| 549 | $ git format-patch HEAD~ | ||
| 550 | </literallayout></para> | ||
| 551 | |||
| 552 | <para>After the command is run, the current directory | ||
| 553 | contains a numbered <filename>.patch</filename> file for | ||
| 554 | the commit.</para> | ||
| 555 | |||
| 556 | <para>If you provide several commits as part of the | ||
| 557 | command, the <filename>git format-patch</filename> command | ||
| 558 | produces a series of numbered files in the current | ||
| 559 | directory – one for each commit. | ||
| 560 | If you have more than one patch, you should also use the | ||
| 561 | <filename>--cover</filename> option with the command, | ||
| 562 | which generates a cover letter as the first "patch" in | ||
| 563 | the series. | ||
| 564 | You can then edit the cover letter to provide a | ||
| 565 | description for the series of patches. | ||
| 566 | For information on the | ||
| 567 | <filename>git format-patch</filename> command, | ||
| 568 | see <filename>GIT_FORMAT_PATCH(1)</filename> displayed | ||
| 569 | using the <filename>man git-format-patch</filename> | ||
| 570 | command. | ||
| 571 | <note> | ||
| 572 | If you are or will be a frequent contributor to the | ||
| 573 | Yocto Project or to OpenEmbedded, you might consider | ||
| 574 | requesting a contrib area and the necessary associated | ||
| 575 | rights. | ||
| 576 | </note> | ||
| 577 | </para></listitem> | ||
| 578 | <listitem><para> | ||
| 579 | <emphasis>Import the Files Into Your Mail Client:</emphasis> | ||
| 580 | Import the files into your mail client by using the | ||
| 581 | <filename>git send-email</filename> command. | ||
| 582 | <note> | ||
| 583 | In order to use <filename>git send-email</filename>, | ||
| 584 | you must have the proper Git packages installed on | ||
| 585 | your host. | ||
| 586 | For Ubuntu, Debian, and Fedora the package is | ||
| 587 | <filename>git-email</filename>. | ||
| 588 | </note></para> | ||
| 589 | |||
| 590 | <para>The <filename>git send-email</filename> command | ||
| 591 | sends email by using a local or remote Mail Transport Agent | ||
| 592 | (MTA) such as <filename>msmtp</filename>, | ||
| 593 | <filename>sendmail</filename>, or through a direct | ||
| 594 | <filename>smtp</filename> configuration in your Git | ||
| 595 | <filename>~/.gitconfig</filename> file. | ||
| 596 | If you are submitting patches through email only, it is | ||
| 597 | very important that you submit them without any whitespace | ||
| 598 | or HTML formatting that either you or your mailer | ||
| 599 | introduces. | ||
| 600 | The maintainer that receives your patches needs to be able | ||
| 601 | to save and apply them directly from your emails. | ||
| 602 | A good way to verify that what you are sending will be | ||
| 603 | applicable by the maintainer is to do a dry run and send | ||
| 604 | them to yourself and then save and apply them as the | ||
| 605 | maintainer would.</para> | ||
| 606 | |||
| 607 | <para>The <filename>git send-email</filename> command is | ||
| 608 | the preferred method for sending your patches using | ||
| 609 | email since there is no risk of compromising whitespace | ||
| 610 | in the body of the message, which can occur when you use | ||
| 611 | your own mail client. | ||
| 612 | The command also has several options that let you | ||
| 613 | specify recipients and perform further editing of the | ||
| 614 | email message. | ||
| 615 | For information on how to use the | ||
| 616 | <filename>git send-email</filename> command, | ||
| 617 | see <filename>GIT-SEND-EMAIL(1)</filename> displayed using | ||
| 618 | the <filename>man git-send-email</filename> command. | ||
| 619 | </para></listitem> | ||
| 620 | </orderedlist> | ||
| 621 | </para> | ||
| 622 | </section> | ||
| 623 | </section> | ||
| 624 | </chapter> | ||
| 625 | <!-- | ||
| 626 | vim: expandtab tw=80 ts=4 | ||
| 627 | --> | ||