summaryrefslogtreecommitdiffstats
path: root/documentation/profile-manual/profile-manual-usage.xml
diff options
context:
space:
mode:
Diffstat (limited to 'documentation/profile-manual/profile-manual-usage.xml')
-rw-r--r--documentation/profile-manual/profile-manual-usage.xml1218
1 files changed, 1218 insertions, 0 deletions
diff --git a/documentation/profile-manual/profile-manual-usage.xml b/documentation/profile-manual/profile-manual-usage.xml
new file mode 100644
index 0000000000..65e17e24a0
--- /dev/null
+++ b/documentation/profile-manual/profile-manual-usage.xml
@@ -0,0 +1,1218 @@
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<para>
10 This chapter helps you understand the Yocto Project as an open source development project.
11 In general, working in an open source environment is very different from working in a
12 closed, proprietary environment.
13 Additionally, the Yocto Project uses specific tools and constructs as part of its development
14 environment.
15 This chapter specifically addresses open source philosophy, licensing issues, code repositories,
16 the open source distributed version control system Git, and best practices using the Yocto Project.
17</para>
18
19<section id='open-source-philosophy'>
20 <title>Open Source Philosophy</title>
21
22 <para>
23 Open source philosophy is characterized by software development directed by peer production
24 and collaboration through an active community of developers.
25 Contrast this to the more standard centralized development models used by commercial software
26 companies where a finite set of developers produces a product for sale using a defined set
27 of procedures that ultimately result in an end product whose architecture and source material
28 are closed to the public.
29 </para>
30
31 <para>
32 Open source projects conceptually have differing concurrent agendas, approaches, and production.
33 These facets of the development process can come from anyone in the public (community) that has a
34 stake in the software project.
35 The open source environment contains new copyright, licensing, domain, and consumer issues
36 that differ from the more traditional development environment.
37 In an open source environment, the end product, source material, and documentation are
38 all available to the public at no cost.
39 </para>
40
41 <para>
42 A benchmark example of an open source project is the Linux Kernel, which was initially conceived
43 and created by Finnish computer science student Linus Torvalds in 1991.
44 Conversely, a good example of a non-open source project is the
45 <trademark class='registered'>Windows</trademark> family of operating
46 systems developed by <trademark class='registered'>Microsoft</trademark> Corporation.
47 </para>
48
49 <para>
50 Wikipedia has a good historical description of the Open Source Philosophy
51 <ulink url='http://en.wikipedia.org/wiki/Open_source'>here</ulink>.
52 You can also find helpful information on how to participate in the Linux Community
53 <ulink url='http://ldn.linuxfoundation.org/book/how-participate-linux-community'>here</ulink>.
54 </para>
55</section>
56
57<section id="usingpoky-changes-collaborate">
58 <title>Using the Yocto Project in a Team Environment</title>
59
60 <para>
61 It might not be immediately clear how you can use the Yocto Project in a team environment,
62 or scale it for a large team of developers.
63 The specifics of any situation determine the best solution.
64 Granted that the Yocto Project offers immense flexibility regarding this, practices do exist
65 that experience has shown work well.
66 </para>
67
68 <para>
69 The core component of any development effort with the Yocto Project is often an
70 automated build and testing framework along with an image generation process.
71 You can use these core components to check that the metadata can be built,
72 highlight when commits break the build, and provide up-to-date images that
73 allow developers to test the end result and use it as a base platform for further
74 development.
75 Experience shows that buildbot is a good fit for this role.
76 What works well is to configure buildbot to make two types of builds:
77 incremental and full (from scratch).
78 See "<ulink url='http://autobuilder.yoctoproject.org:8010/'>Welcome to the buildbot for the Yocto Project</ulink>"
79 for an example implementation that uses buildbot.
80 </para>
81
82 <para>
83 You can tie an incremental build to a commit hook that triggers the build
84 each time a commit is made to the metadata.
85 This practice results in useful acid tests that determine whether a given commit
86 breaks the build in some serious way.
87 Associating a build to a commit can catch a lot of simple errors.
88 Furthermore, the tests are fast so developers can get quick feedback on changes.
89 </para>
90
91 <para>
92 Full builds build and test everything from the ground up.
93 These types of builds usually happen at predetermined times like during the
94 night when the machine load is low.
95 </para>
96
97 <para>
98 Most teams have many pieces of software undergoing active development at any given time.
99 You can derive large benefits by putting these pieces under the control of a source
100 control system that is compatible (i.e. Git or Subversion (SVN)) with the OpenEmbedded
101 build system that the Yocto Project uses.
102 You can then set the autobuilder to pull the latest revisions of the packages
103 and test the latest commits by the builds.
104 This practice quickly highlights issues.
105 The build system easily supports testing configurations that use both a
106 stable known good revision and a floating revision.
107 The build system can also take just the changes from specific source control branches.
108 This capability allows you to track and test specific changes.
109 </para>
110
111 <para>
112 Perhaps the hardest part of setting this up is defining the software project or
113 the metadata policies that surround the different source control systems.
114 Of course circumstances will be different in each case.
115 However, this situation reveals one of the Yocto Project's advantages -
116 the system itself does not
117 force any particular policy on users, unlike a lot of build systems.
118 The system allows the best policies to be chosen for the given circumstances.
119 </para>
120
121 <para>
122 In general, best practices exist that make your work with the Yocto
123 Project easier in a team environment.
124 This list presents some of these practices you might consider following.
125 Of course, you need to understand that you do not have to follow these
126 practices and your setup can be totally controlled and customized by
127 your team:
128 <itemizedlist>
129 <listitem><para>Use <link linkend='git'>Git</link>
130 as the source control system.</para></listitem>
131 <listitem><para>Maintain your metadata in layers that make sense
132 for your situation.
133 See the "<link linkend='understanding-and-creating-layers'>Understanding
134 and Creating Layers</link>" section for more information on
135 layers.</para></listitem>
136 <listitem><para>Separate the project's metadata and code by using
137 separate Git repositories.
138 See the "<link linkend='yocto-project-repositories'>Yocto Project
139 Source Repositories</link>" section for information on these
140 repositories.
141 See the "<link linkend='getting-setup'>Getting Set Up</link>" section
142 for information on how to set up various Yocto Project related
143 Git repositories.</para></listitem>
144 <listitem><para>Set up the directory for the shared state cache
145 (<ulink url='&YOCTO_DOCS_REF_URL;#var-SSTATE_DIR'><filename>SSTATE_DIR</filename></ulink>)
146 where they make sense.
147 For example, set up the sstate cache for developers using the
148 same office and share source directories on the developer's
149 machines.</para></listitem>
150 <listitem><para>Set up an autobuilder and have it populate the
151 sstate cache and source directories.</para></listitem>
152 </itemizedlist>
153 </para>
154</section>
155
156<section id='yocto-project-repositories'>
157 <title>Yocto Project Source Repositories</title>
158
159 <para>
160 The Yocto Project team maintains complete source repositories for all Yocto Project files
161 at <ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi'></ulink>.
162 This web-based source code browser is organized into categories by function such as
163 IDE Plugins, Matchbox, Poky, Yocto Linux Kernel, and so forth.
164 From the interface, you can click on any particular item in the "Name" column and
165 see the URL at the bottom of the page that you need to set up a Git repository for
166 that particular item.
167 Having a local Git repository of the Source Directory (poky) allows you to
168 make changes, contribute to the history, and ultimately enhance the Yocto Project's
169 tools, Board Support Packages, and so forth.
170 </para>
171
172 <para>
173 Conversely, if you are a developer that is not interested in contributing back to the
174 Yocto Project, you have the ability to simply download and extract release tarballs
175 and use them within the Yocto Project environment.
176 All that is required is a particular release of the Yocto Project and
177 your application source code.
178 </para>
179
180 <para>
181 For any supported release of Yocto Project, you can go to the Yocto Project website’s
182 <ulink url='&YOCTO_HOME_URL;/download'>download page</ulink> and get a
183 tarball of the release.
184 You can also go to this site to download any supported BSP tarballs.
185 Unpacking the tarball gives you a hierarchical Source Directory that lets you develop
186 using the Yocto Project.
187 </para>
188
189 <para>
190 Once you are set up through either tarball extraction or a checkout of Git repositories,
191 you are ready to develop.
192 </para>
193
194 <para>
195 In summary, here is where you can get the project files needed for development:
196 <itemizedlist>
197 <listitem><para id='source-repositories'><emphasis><ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi'>Source Repositories:</ulink></emphasis>
198 This area contains IDE Plugins, Matchbox, Poky, Poky Support, Tools, Yocto Linux Kernel, and Yocto
199 Metadata Layers.
200 You can create local copies of Git repositories for each of these areas.</para>
201 <para>
202 <imagedata fileref="figures/source-repos.png" align="center" width="6in" depth="4in" />
203 </para></listitem>
204 <listitem><para><anchor id='index-downloads' /><emphasis><ulink url='&YOCTO_DL_URL;/releases/'>Index of /releases:</ulink></emphasis>
205 This area contains index releases such as
206 the <trademark class='trade'>Eclipse</trademark>
207 Yocto Plug-in, miscellaneous support, poky, pseudo, installers for cross-development toolchains,
208 and all released versions of Yocto Project in the form of images or tarballs.
209 Downloading and extracting these files does not produce a local copy of the
210 Git repository but rather a snapshot of a particular release or image.</para>
211 <para>
212 <imagedata fileref="figures/index-downloads.png" align="center" width="6in" depth="4in" />
213 </para></listitem>
214 <listitem><para><emphasis><ulink url='&YOCTO_HOME_URL;/download'>Yocto Project Download Page</ulink></emphasis>
215 This page on the Yocto Project website allows you to download any Yocto Project
216 release or Board Support Package (BSP) in tarball form.
217 The tarballs are similar to those found in the
218 <ulink url='&YOCTO_DL_URL;/releases/'>Index of /releases:</ulink> area.</para>
219 <para>
220 <imagedata fileref="figures/yp-download.png" align="center" width="6in" depth="4in" />
221 </para></listitem>
222 </itemizedlist>
223 </para>
224</section>
225
226<section id='yocto-project-terms'>
227 <title>Yocto Project Terms</title>
228
229 <para>
230 Following is a list of terms and definitions users new to the Yocto Project development
231 environment might find helpful.
232 While some of these terms are universal, the list includes them just in case:
233 <itemizedlist>
234 <listitem><para><emphasis>Append Files:</emphasis> Files that append build information to
235 a recipe file.
236 Append files are known as BitBake append files and <filename>.bbappend</filename> files.
237 The OpenEmbedded build system expects every append file to have a corresponding and
238 underlying recipe (<filename>.bb</filename>) file.
239 Furthermore, the append file and the underlying recipe must have the same root filename.
240 The filenames can differ only in the file type suffix used (e.g.
241 <filename>formfactor_0.0.bb</filename> and <filename>formfactor_0.0.bbappend</filename>).
242 </para>
243 <para>Information in append files overrides the information in the similarly-named recipe file.
244 For an example of an append file in use, see the
245 "<link linkend='using-bbappend-files'>Using .bbappend Files</link>" section.
246 </para></listitem>
247 <listitem><para id='bitbake-term'><emphasis>BitBake:</emphasis>
248 The task executor and scheduler used by
249 the OpenEmbedded build system to build images.
250 For more information on BitBake, see the BitBake documentation
251 in the <filename>bitbake/doc/manual</filename> directory of the
252 <link linkend='source-directory'>Source Directory</link>.</para></listitem>
253 <listitem>
254 <para id='build-directory'><emphasis>Build Directory:</emphasis>
255 This term refers to the area used by the OpenEmbedded build system for builds.
256 The area is created when you <filename>source</filename> the setup
257 environment script that is found in the Source Directory
258 (i.e. <filename>&OE_INIT_FILE;</filename>).
259 The <ulink url='&YOCTO_DOCS_REF_URL;#var-TOPDIR'><filename>TOPDIR</filename></ulink>
260 variable points to the Build Directory.</para>
261
262 <para>You have a lot of flexibility when creating the Build Directory.
263 Following are some examples that show how to create the directory:
264 <itemizedlist>
265 <listitem><para>Create the Build Directory in your current working directory
266 and name it <filename>build</filename>.
267 This is the default behavior.
268 <literallayout class='monospaced'>
269 $ source &OE_INIT_PATH;
270 </literallayout></para></listitem>
271 <listitem><para>Provide a directory path and specifically name the build
272 directory.
273 This next example creates a Build Directory named <filename>YP-&POKYVERSION;</filename>
274 in your home directory within the directory <filename>mybuilds</filename>.
275 If <filename>mybuilds</filename> does not exist, the directory is created for you:
276 <literallayout class='monospaced'>
277 $ source &OE_INIT_PATH; $HOME/mybuilds/YP-&POKYVERSION;
278 </literallayout></para></listitem>
279 <listitem><para>Provide an existing directory to use as the Build Directory.
280 This example uses the existing <filename>mybuilds</filename> directory
281 as the Build Directory.
282 <literallayout class='monospaced'>
283 $ source &OE_INIT_PATH; $HOME/mybuilds/
284 </literallayout></para></listitem>
285 </itemizedlist>
286 </para></listitem>
287 <listitem><para><emphasis>Build System:</emphasis> In the context of the Yocto Project
288 this term refers to the OpenEmbedded build system used by the project.
289 This build system is based on the project known as "Poky."
290 For some historical information about Poky, see the
291 <link linkend='poky'>Poky</link> term further along in this section.
292 </para></listitem>
293 <listitem><para><emphasis>Classes:</emphasis> Files that provide for logic encapsulation
294 and inheritance allowing commonly used patterns to be defined once and easily used
295 in multiple recipes.
296 Class files end with the <filename>.bbclass</filename> filename extension.
297 </para></listitem>
298 <listitem><para><emphasis>Configuration File:</emphasis> Configuration information in various
299 <filename>.conf</filename> files provides global definitions of variables.
300 The <filename>conf/local.conf</filename> configuration file in the
301 <link linkend='build-directory'>Build Directory</link>
302 contains user-defined variables that affect each build.
303 The <filename>meta-yocto/conf/distro/poky.conf</filename> configuration file
304 defines Yocto ‘distro’ configuration
305 variables used only when building with this policy.
306 Machine configuration files, which
307 are located throughout the
308 <link linkend='source-directory'>Source Directory</link>, define
309 variables for specific hardware and are only used when building for that target
310 (e.g. the <filename>machine/beagleboard.conf</filename> configuration file defines
311 variables for the Texas Instruments ARM Cortex-A8 development board).
312 Configuration files end with a <filename>.conf</filename> filename extension.
313 </para></listitem>
314 <listitem><para><emphasis>Cross-Development Toolchain:</emphasis>
315 A collection of software development
316 tools and utilities that allow you to develop software for targeted architectures.
317 This toolchain contains cross-compilers, linkers, and debuggers that are specific to
318 an architecture.
319 You can use the OpenEmbedded build system to build a cross-development toolchain
320 installer that when run installs the toolchain that contains the development tools you
321 need to cross-compile and test your software.
322 The Yocto Project ships with images that contain installers for
323 toolchains for supported architectures as well.
324 Sometimes this toolchain is referred to as the meta-toolchain.</para></listitem>
325 <listitem><para><emphasis>Image:</emphasis> An image is the result produced when
326 BitBake processes a given collection of recipes and related metadata.
327 Images are the binary output that run on specific hardware or QEMU
328 and for specific use cases.
329 For a list of the supported image types that the Yocto Project provides, see the
330 "<ulink url='&YOCTO_DOCS_REF_URL;#ref-images'>Images</ulink>"
331 chapter in the Yocto Project Reference Manual.</para></listitem>
332 <listitem><para id='layer'><emphasis>Layer:</emphasis> A collection of recipes representing the core,
333 a BSP, or an application stack.
334 For a discussion on BSP Layers, see the
335 "<ulink url='&YOCTO_DOCS_BSP_URL;#bsp-layers'>BSP Layers</ulink>"
336 section in the Yocto Project Board Support Packages (BSP) Developer's Guide.</para></listitem>
337 <listitem><para id='metadata'><emphasis>Metadata:</emphasis> The files that BitBake parses when
338 building an image.
339 Metadata includes recipes, classes, and configuration files.</para></listitem>
340 <listitem><para id='oe-core'><emphasis>OE-Core:</emphasis> A core set of metadata originating
341 with OpenEmbedded (OE) that is shared between OE and the Yocto Project.
342 This metadata is found in the <filename>meta</filename> directory of the source
343 directory.</para></listitem>
344 <listitem><para><emphasis>Package:</emphasis> In the context of the Yocto Project,
345 this term refers to the packaged output from a baked recipe.
346 A package is generally the compiled binaries produced from the recipe's sources.
347 You ‘bake’ something by running it through BitBake.</para>
348 <para>It is worth noting that the term "package" can, in general, have subtle
349 meanings. For example, the packages refered to in the
350 "<ulink url='&YOCTO_DOCS_QS_URL;#packages'>The Packages</ulink>" section are
351 compiled binaries that when installed add functionality to your Linux
352 distribution.</para>
353 <para>Another point worth noting is that historically within the Yocto Project,
354 recipes were referred to as packages - thus, the existence of several BitBake
355 variables that are seemingly mis-named,
356 (e.g. <ulink url='&YOCTO_DOCS_REF_URL;#var-PR'><filename>PR</filename></ulink>,
357 <ulink url='&YOCTO_DOCS_REF_URL;#var-PRINC'><filename>PRINC</filename></ulink>,
358 <ulink url='&YOCTO_DOCS_REF_URL;#var-PV'><filename>PV</filename></ulink>, and
359 <ulink url='&YOCTO_DOCS_REF_URL;#var-PE'><filename>PE</filename></ulink>).
360 </para></listitem>
361 <listitem><para id='poky'><emphasis>Poky:</emphasis> The term "poky" can mean several things.
362 In its most general sense, it is an open-source project that was initially developed
363 by OpenedHand. With OpenedHand, poky was developed off of the existing OpenEmbedded
364 build system becoming a build system for embedded images.
365 After Intel Corporation acquired OpenedHand, the project poky became the basis for
366 the Yocto Project's build system.
367 Within the Yocto Project source repositories, poky exists as a separate Git repository
368 that can be cloned to yield a local copy on the host system.
369 Thus, "poky" can refer to the local copy of the Source Directory used to develop within
370 the Yocto Project.</para></listitem>
371 <listitem><para><emphasis>Recipe:</emphasis> A set of instructions for building packages.
372 A recipe describes where you get source code and which patches to apply.
373 Recipes describe dependencies for libraries or for other recipes, and they
374 also contain configuration and compilation options.
375 Recipes contain the logical unit of execution, the software/images to build, and
376 use the <filename>.bb</filename> file extension.</para></listitem>
377 <listitem>
378 <para id='source-directory'><emphasis>Source Directory:</emphasis>
379 This term refers to the directory structure created as a result of either downloading
380 and unpacking a Yocto Project release tarball or creating a local copy of
381 the <filename>poky</filename> Git repository
382 <filename>git://git.yoctoproject.org/poky</filename>.
383 Sometimes you might hear the term "poky directory" used to refer to this
384 directory structure.
385 <note>
386 The OpenEmbedded build system does not support file or directory names that
387 contain spaces.
388 Be sure that the Source Directory you use does not contain these types
389 of names.
390 </note></para>
391 <para>The Source Directory contains BitBake, Documentation, metadata and
392 other files that all support the Yocto Project.
393 Consequently, you must have the Source Directory in place on your development
394 system in order to do any development using the Yocto Project.</para>
395
396 <para>For tarball expansion, the name of the top-level directory of the Source Directory
397 is derived from the Yocto Project release tarball.
398 For example, downloading and unpacking <filename>&YOCTO_POKY_TARBALL;</filename>
399 results in a Source Directory whose top-level folder is named
400 <filename>&YOCTO_POKY;</filename>.
401 If you create a local copy of the Git repository, then you can name the repository
402 anything you like.
403 Throughout much of the documentation, <filename>poky</filename> is used as the name of
404 the top-level folder of the local copy of the poky Git repository.
405 So, for example, cloning the <filename>poky</filename> Git repository results in a
406 local Git repository whose top-level folder is also named <filename>poky</filename>.</para>
407
408 <para>It is important to understand the differences between the Source Directory created
409 by unpacking a released tarball as compared to cloning
410 <filename>git://git.yoctoproject.org/poky</filename>.
411 When you unpack a tarball, you have an exact copy of the files based on the time of
412 release - a fixed release point.
413 Any changes you make to your local files in the Source Directory are on top of the release.
414 On the other hand, when you clone the <filename>poky</filename> Git repository, you have an
415 active development repository.
416 In this case, any local changes you make to the Source Directory can be later applied
417 to active development branches of the upstream <filename>poky</filename> Git
418 repository.</para>
419
420 <para>Finally, if you want to track a set of local changes while starting from the same point
421 as a release tarball, you can create a local Git branch that
422 reflects the exact copy of the files at the time of their release.
423 You do this by using Git tags that are part of the repository.</para>
424
425 <para>For more information on concepts related to Git repositories, branches, and tags,
426 see the
427 "<link linkend='repositories-tags-and-branches'>Repositories, Tags, and Branches</link>"
428 section.</para></listitem>
429 <listitem><para><emphasis>Tasks:</emphasis> Arbitrary groups of software Recipes.
430 You simply use Tasks to hold recipes that, when built, usually accomplish a single task.
431 For example, a task could contain the recipes for a company’s proprietary or value-add software.
432 Or, the task could contain the recipes that enable graphics.
433 A task is really just another recipe.
434 Because task files are recipes, they end with the <filename>.bb</filename> filename
435 extension.</para></listitem>
436 <listitem><para><emphasis>Upstream:</emphasis> A reference to source code or repositories
437 that are not local to the development system but located in a master area that is controlled
438 by the maintainer of the source code.
439 For example, in order for a developer to work on a particular piece of code, they need to
440 first get a copy of it from an "upstream" source.</para></listitem>
441 </itemizedlist>
442 </para>
443</section>
444
445<section id='licensing'>
446 <title>Licensing</title>
447
448 <para>
449 Because open source projects are open to the public, they have different licensing structures in place.
450 License evolution for both Open Source and Free Software has an interesting history.
451 If you are interested in this history, you can find basic information here:
452 <itemizedlist>
453 <listitem><para><ulink url='http://en.wikipedia.org/wiki/Open-source_license'>Open source license history</ulink>
454 </para></listitem>
455 <listitem><para><ulink url='http://en.wikipedia.org/wiki/Free_software_license'>Free software license
456 history</ulink></para></listitem>
457 </itemizedlist>
458 </para>
459
460 <para>
461 In general, the Yocto Project is broadly licensed under the Massachusetts Institute of Technology
462 (MIT) License.
463 MIT licensing permits the reuse of software within proprietary software as long as the
464 license is distributed with that software.
465 MIT is also compatible with the GNU General Public License (GPL).
466 Patches to the Yocto Project follow the upstream licensing scheme.
467 You can find information on the MIT license at
468 <ulink url='http://www.opensource.org/licenses/mit-license.php'>here</ulink>.
469 You can find information on the GNU GPL <ulink url='http://www.opensource.org/licenses/LGPL-3.0'>
470 here</ulink>.
471 </para>
472
473 <para>
474 When you build an image using the Yocto Project, the build process uses a
475 known list of licenses to ensure compliance.
476 You can find this list in the Yocto Project files directory at
477 <filename>meta/files/common-licenses</filename>.
478 Once the build completes, the list of all licenses found and used during that build are
479 kept in the
480 <link linkend='build-directory'>Build Directory</link> at
481 <filename>tmp/deploy/images/licenses</filename>.
482 </para>
483
484 <para>
485 If a module requires a license that is not in the base list, the build process
486 generates a warning during the build.
487 These tools make it easier for a developer to be certain of the licenses with which
488 their shipped products must comply.
489 However, even with these tools it is still up to the developer to resolve potential licensing issues.
490 </para>
491
492 <para>
493 The base list of licenses used by the build process is a combination of the Software Package
494 Data Exchange (SPDX) list and the Open Source Initiative (OSI) projects.
495 <ulink url='http://spdx.org'>SPDX Group</ulink> is a working group of the Linux Foundation
496 that maintains a specification
497 for a standard format for communicating the components, licenses, and copyrights
498 associated with a software package.
499 <ulink url='http://opensource.org'>OSI</ulink> is a corporation dedicated to the Open Source
500 Definition and the effort for reviewing and approving licenses that are OSD-conformant.
501 </para>
502
503 <para>
504 You can find a list of the combined SPDX and OSI licenses that the Yocto Project uses
505 <ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi/poky/tree/meta/files/common-licenses'>here</ulink>.
506 This wiki page discusses the license infrastructure used by the Yocto Project.
507 </para>
508
509 <para>
510 For information that can help you to maintain compliance with various open source licensing
511 during the lifecycle of a product created using the Yocto Project, see the
512 "<link linkend='maintaining-open-source-license-compliance-during-your-products-lifecycle'>Maintaining Open Source License Compliance During Your Product's Lifecycle</link>" section.
513 </para>
514</section>
515
516<section id='git'>
517 <title>Git</title>
518
519 <para>
520 The Yocto Project uses Git, which is a free, open source distributed version control system.
521 Git supports distributed development, non-linear development, and can handle large projects.
522 It is best that you have some fundamental understanding of how Git tracks projects and
523 how to work with Git if you are going to use Yocto Project for development.
524 This section provides a quick overview of how Git works and provides you with a summary
525 of some essential Git commands.
526 </para>
527
528 <para>
529 For more information on Git, see
530 <ulink url='http://git-scm.com/documentation'></ulink>.
531 If you need to download Git, go to <ulink url='http://git-scm.com/download'></ulink>.
532 </para>
533
534 <section id='repositories-tags-and-branches'>
535 <title>Repositories, Tags, and Branches</title>
536
537 <para>
538 As mentioned earlier in section
539 "<link linkend='yocto-project-repositories'>Yocto Project Source Repositories</link>",
540 the Yocto Project maintains source repositories at
541 <ulink url='&YOCTO_GIT_URL;/cgit.cgi'></ulink>.
542 If you look at this web-interface of the repositories, each item is a separate
543 Git repository.
544 </para>
545
546 <para>
547 Git repositories use branching techniques that track content change (not files)
548 within a project (e.g. a new feature or updated documentation).
549 Creating a tree-like structure based on project divergence allows for excellent historical
550 information over the life of a project.
551 This methodology also allows for an environment in which you can do lots of
552 local experimentation on a project as you develop changes or new features.
553 </para>
554
555 <para>
556 A Git repository represents all development efforts for a given project.
557 For example, the Git repository <filename>poky</filename> contains all changes
558 and developments for Poky over the course of its entire life.
559 That means that all changes that make up all releases are captured.
560 The repository maintains a complete history of changes.
561 </para>
562
563 <para>
564 You can create a local copy of any repository by "cloning" it with the Git
565 <filename>clone</filename> command.
566 When you clone a Git repository, you end up with an identical copy of the
567 repository on your development system.
568 Once you have a local copy of a repository, you can take steps to develop locally.
569 For examples on how to clone Git repositories, see the section
570 "<link linkend='getting-setup'>Getting Set Up</link>" earlier in this manual.
571 </para>
572
573 <para>
574 It is important to understand that Git tracks content change and not files.
575 Git uses "branches" to organize different development efforts.
576 For example, the <filename>poky</filename> repository has
577 <filename>bernard</filename>,
578 <filename>edison</filename>, <filename>denzil</filename>, <filename>danny</filename>
579 and <filename>master</filename> branches among others.
580 You can see all the branches by going to
581 <ulink url='&YOCTO_GIT_URL;/cgit.cgi/poky/'></ulink> and
582 clicking on the
583 <filename><ulink url='&YOCTO_GIT_URL;/cgit.cgi/poky/refs/heads'>[...]</ulink></filename>
584 link beneath the "Branch" heading.
585 </para>
586
587 <para>
588 Each of these branches represents a specific area of development.
589 The <filename>master</filename> branch represents the current or most recent
590 development.
591 All other branches represent off-shoots of the <filename>master</filename>
592 branch.
593 </para>
594
595 <para>
596 When you create a local copy of a Git repository, the copy has the same set
597 of branches as the original.
598 This means you can use Git to create a local working area (also called a branch)
599 that tracks a specific development branch from the source Git repository.
600 in other words, you can define your local Git environment to work on any development
601 branch in the repository.
602 To help illustrate, here is a set of commands that creates a local copy of the
603 <filename>poky</filename> Git repository and then creates and checks out a local
604 Git branch that tracks the Yocto Project &DISTRO; Release (&DISTRO_NAME;) development:
605 <literallayout class='monospaced'>
606 $ cd ~
607 $ git clone git://git.yoctoproject.org/poky
608 $ cd poky
609 $ git checkout -b &DISTRO_NAME; origin/&DISTRO_NAME;
610 </literallayout>
611 In this example, the name of the top-level directory of your local Yocto Project
612 Files Git repository is <filename>poky</filename>,
613 and the name of the local working area (or local branch) you have created and checked
614 out is <filename>&DISTRO_NAME;</filename>.
615 The files in your repository now reflect the same files that are in the
616 <filename>&DISTRO_NAME;</filename> development branch of the Yocto Project's
617 <filename>poky</filename> repository.
618 It is important to understand that when you create and checkout a
619 local working branch based on a branch name,
620 your local environment matches the "tip" of that development branch
621 at the time you created your local branch, which could be
622 different than the files at the time of a similarly named release.
623 In other words, creating and checking out a local branch based on the
624 <filename>&DISTRO_NAME;</filename> branch name is not the same as
625 cloning and checking out the <filename>master</filename> branch.
626 Keep reading to see how you create a local snapshot of a Yocto Project Release.
627 </para>
628
629 <para>
630 Git uses "tags" to mark specific changes in a repository.
631 Typically, a tag is used to mark a special point such as the final change
632 before a project is released.
633 You can see the tags used with the <filename>poky</filename> Git repository
634 by going to <ulink url='&YOCTO_GIT_URL;/cgit.cgi/poky/'></ulink> and
635 clicking on the
636 <filename><ulink url='&YOCTO_GIT_URL;/cgit.cgi/poky/refs/tags'>[...]</ulink></filename>
637 link beneath the "Tag" heading.
638 </para>
639
640 <para>
641 Some key tags are <filename>bernard-5.0</filename>, <filename>denzil-7.0</filename>,
642 and <filename>&DISTRO_NAME;-&POKYVERSION;</filename>.
643 These tags represent Yocto Project releases.
644 </para>
645
646 <para>
647 When you create a local copy of the Git repository, you also have access to all the
648 tags.
649 Similar to branches, you can create and checkout a local working Git branch based
650 on a tag name.
651 When you do this, you get a snapshot of the Git repository that reflects
652 the state of the files when the change was made associated with that tag.
653 The most common use is to checkout a working branch that matches a specific
654 Yocto Project release.
655 Here is an example:
656 <literallayout class='monospaced'>
657 $ cd ~
658 $ git clone git://git.yoctoproject.org/poky
659 $ cd poky
660 $ git checkout -b my-&DISTRO_NAME;-&POKYVERSION; &DISTRO_NAME;-&POKYVERSION;
661 </literallayout>
662 In this example, the name of the top-level directory of your local Yocto Project
663 Files Git repository is <filename>poky</filename>.
664 And, the name of the local branch you have created and checked out is
665 <filename>my-&DISTRO_NAME;-&POKYVERSION;</filename>.
666 The files in your repository now exactly match the Yocto Project &DISTRO;
667 Release tag (<filename>&DISTRO_NAME;-&POKYVERSION;</filename>).
668 It is important to understand that when you create and checkout a local
669 working branch based on a tag, your environment matches a specific point
670 in time and not a development branch.
671 </para>
672 </section>
673
674 <section id='basic-commands'>
675 <title>Basic Commands</title>
676
677 <para>
678 Git has an extensive set of commands that lets you manage changes and perform
679 collaboration over the life of a project.
680 Conveniently though, you can manage with a small set of basic operations and workflows
681 once you understand the basic philosophy behind Git.
682 You do not have to be an expert in Git to be functional.
683 A good place to look for instruction on a minimal set of Git commands is
684 <ulink url='http://git-scm.com/documentation'>here</ulink>.
685 If you need to download Git, you can do so
686 <ulink url='http://git-scm.com/download'>here</ulink>.
687 </para>
688
689 <para>
690 If you don’t know much about Git, we suggest you educate
691 yourself by visiting the links previously mentioned.
692 </para>
693
694 <para>
695 The following list briefly describes some basic Git operations as a way to get started.
696 As with any set of commands, this list (in most cases) simply shows the base command and
697 omits the many arguments they support.
698 See the Git documentation for complete descriptions and strategies on how to use these commands:
699 <itemizedlist>
700 <listitem><para><emphasis><filename>git init</filename>:</emphasis> Initializes an empty Git repository.
701 You cannot use Git commands unless you have a <filename>.git</filename> repository.</para></listitem>
702 <listitem><para><emphasis><filename>git clone</filename>:</emphasis> Creates a clone of a repository.
703 During collaboration, this command allows you to create a local repository that is on
704 equal footing with a fellow developer’s repository.</para></listitem>
705 <listitem><para><emphasis><filename>git add</filename>:</emphasis> Adds updated file contents
706 to the index that
707 Git uses to track changes.
708 You must add all files that have changed before you can commit them.</para></listitem>
709 <listitem><para><emphasis><filename>git commit</filename>:</emphasis> Creates a “commit” that documents
710 the changes you made.
711 Commits are used for historical purposes, for determining if a maintainer of a project
712 will allow the change, and for ultimately pushing the change from your local Git repository
713 into the project’s upstream (or master) repository.</para></listitem>
714 <listitem><para><emphasis><filename>git status</filename>:</emphasis> Reports any modified files that
715 possibly need to be added and committed.</para></listitem>
716 <listitem><para><emphasis><filename>git checkout &lt;branch-name&gt;</filename>:</emphasis> Changes
717 your working branch.
718 This command is analogous to “cd”.</para></listitem>
719 <listitem><para><emphasis><filename>git checkout –b &lt;working-branch&gt;</filename>:</emphasis> Creates
720 a working branch on your local machine where you can isolate work.
721 It is a good idea to use local branches when adding specific features or changes.
722 This way if you don’t like what you have done you can easily get rid of the work.</para></listitem>
723 <listitem><para><emphasis><filename>git branch</filename>:</emphasis> Reports
724 existing local branches and
725 tells you the branch in which you are currently working.</para></listitem>
726 <listitem><para><emphasis><filename>git branch -D &lt;branch-name&gt;</filename>:</emphasis>
727 Deletes an existing local branch.
728 You need to be in a local branch other than the one you are deleting
729 in order to delete <filename>&lt;branch-name&gt;</filename>.</para></listitem>
730 <listitem><para><emphasis><filename>git pull</filename>:</emphasis> Retrieves information
731 from an upstream Git
732 repository and places it in your local Git repository.
733 You use this command to make sure you are synchronized with the repository
734 from which you are basing changes (.e.g. the master branch).</para></listitem>
735 <listitem><para><emphasis><filename>git push</filename>:</emphasis> Sends all your local changes you
736 have committed to an upstream Git repository (e.g. a contribution repository).
737 The maintainer of the project draws from these repositories when adding your changes to the
738 project’s master repository.</para></listitem>
739 <listitem><para><emphasis><filename>git merge</filename>:</emphasis> Combines or adds changes from one
740 local branch of your repository with another branch.
741 When you create a local Git repository, the default branch is named “master”.
742 A typical workflow is to create a temporary branch for isolated work, make and commit your
743 changes, switch to your local master branch, merge the changes from the temporary branch into the
744 local master branch, and then delete the temporary branch.</para></listitem>
745 <listitem><para><emphasis><filename>git cherry-pick</filename>:</emphasis> Choose and apply specific
746 commits from one branch into another branch.
747 There are times when you might not be able to merge all the changes in one branch with
748 another but need to pick out certain ones.</para></listitem>
749 <listitem><para><emphasis><filename>gitk</filename>:</emphasis> Provides a GUI view of the branches
750 and changes in your local Git repository.
751 This command is a good way to graphically see where things have diverged in your
752 local repository.</para></listitem>
753 <listitem><para><emphasis><filename>git log</filename>:</emphasis> Reports a history of your changes to the
754 repository.</para></listitem>
755 <listitem><para><emphasis><filename>git diff</filename>:</emphasis> Displays line-by-line differences
756 between your local working files and the same files in the upstream Git repository that your
757 branch currently tracks.</para></listitem>
758 </itemizedlist>
759 </para>
760 </section>
761</section>
762
763<section id='workflows'>
764 <title>Workflows</title>
765
766 <para>
767 This section provides some overview on workflows using Git.
768 In particular, the information covers basic practices that describe roles and actions in a
769 collaborative development environment.
770 Again, if you are familiar with this type of development environment, you might want to just
771 skip this section.
772 </para>
773
774 <para>
775 The Yocto Project files are maintained using Git in a "master" branch whose Git history
776 tracks every change and whose structure provides branches for all diverging functionality.
777 Although there is no need to use Git, many open source projects do so.
778 For the Yocto Project, a key individual called the "maintainer" is responsible for the "master"
779 branch of the Git repository.
780 The "master" branch is the “upstream” repository where the final builds of the project occur.
781 The maintainer is responsible for allowing changes in from other developers and for
782 organizing the underlying branch structure to reflect release strategies and so forth.
783 <note>You can see who is the maintainer for Yocto Project files by examining the
784 <filename>maintainers.inc</filename> file in the Yocto Project
785 <filename>meta-yocto/conf/distro/include</filename> directory.</note>
786 </para>
787
788 <para>
789 The project also has contribution repositories known as “contrib” areas.
790 These areas temporarily hold changes to the project that have been submitted or committed
791 by the Yocto Project development team and by community members that contribute to the project.
792 The maintainer determines if the changes are qualified to be moved from the "contrib" areas
793 into the "master" branch of the Git repository.
794 </para>
795
796 <para>
797 Developers (including contributing community members) create and maintain cloned repositories
798 of the upstream "master" branch.
799 These repositories are local to their development platforms and are used to develop changes.
800 When a developer is satisfied with a particular feature or change, they “push” the changes
801 to the appropriate "contrib" repository.
802 </para>
803
804 <para>
805 Developers are responsible for keeping their local repository up-to-date with "master".
806 They are also responsible for straightening out any conflicts that might arise within files
807 that are being worked on simultaneously by more than one person.
808 All this work is done locally on the developer’s machine before anything is pushed to a
809 "contrib" area and examined at the maintainer’s level.
810 </para>
811
812 <para>
813 A somewhat formal method exists by which developers commit changes and push them into the
814 "contrib" area and subsequently request that the maintainer include them into "master"
815 This process is called “submitting a patch” or “submitting a change.”
816 For information on submitting patches and changes, see the
817 "<link linkend='how-to-submit-a-change'>How to Submit a Change</link>" section.
818 </para>
819
820 <para>
821 To summarize the environment: we have a single point of entry for changes into the project’s
822 "master" branch of the Git repository, which is controlled by the project’s maintainer.
823 And, we have a set of developers who independently develop, test, and submit changes
824 to "contrib" areas for the maintainer to examine.
825 The maintainer then chooses which changes are going to become a permanent part of the project.
826 </para>
827
828 <para>
829 <imagedata fileref="figures/git-workflow.png" width="6in" depth="3in" align="left" scalefit="1" />
830 </para>
831
832 <para>
833 While each development environment is unique, there are some best practices or methods
834 that help development run smoothly.
835 The following list describes some of these practices.
836 For more information about Git workflows, see the workflow topics in the
837 <ulink url='http://book.git-scm.com'>Git Community Book</ulink>.
838 <itemizedlist>
839 <listitem><para><emphasis>Make Small Changes:</emphasis> It is best to keep the changes you commit
840 small as compared to bundling many disparate changes into a single commit.
841 This practice not only keeps things manageable but also allows the maintainer
842 to more easily include or refuse changes.</para>
843 <para>It is also good practice to leave the repository in a state that allows you to
844 still successfully build your project. In other words, do not commit half of a feature,
845 then add the other half in a separate, later commit.
846 Each commit should take you from one buildable project state to another
847 buildable state.</para></listitem>
848 <listitem><para><emphasis>Use Branches Liberally:</emphasis> It is very easy to create, use, and
849 delete local branches in your working Git repository.
850 You can name these branches anything you like.
851 It is helpful to give them names associated with the particular feature or change
852 on which you are working.
853 Once you are done with a feature or change, simply discard the branch.</para></listitem>
854 <listitem><para><emphasis>Merge Changes:</emphasis> The <filename>git merge</filename>
855 command allows you to take the
856 changes from one branch and fold them into another branch.
857 This process is especially helpful when more than a single developer might be working
858 on different parts of the same feature.
859 Merging changes also automatically identifies any collisions or “conflicts”
860 that might happen as a result of the same lines of code being altered by two different
861 developers.</para></listitem>
862 <listitem><para><emphasis>Manage Branches:</emphasis> Because branches are easy to use, you should
863 use a system where branches indicate varying levels of code readiness.
864 For example, you can have a “work” branch to develop in, a “test” branch where the code or
865 change is tested, a “stage” branch where changes are ready to be committed, and so forth.
866 As your project develops, you can merge code across the branches to reflect ever-increasing
867 stable states of the development.</para></listitem>
868 <listitem><para><emphasis>Use Push and Pull:</emphasis> The push-pull workflow is based on the
869 concept of developers “pushing” local commits to a remote repository, which is
870 usually a contribution repository.
871 This workflow is also based on developers “pulling” known states of the project down into their
872 local development repositories.
873 The workflow easily allows you to pull changes submitted by other developers from the
874 upstream repository into your work area ensuring that you have the most recent software
875 on which to develop.
876 The Yocto Project has two scripts named <filename>create-pull-request</filename> and
877 <filename>send-pull-request</filename> that ship with the release to facilitate this
878 workflow.
879 You can find these scripts in the local Yocto Project files Git repository in
880 the <filename>scripts</filename> directory.</para>
881 <para>You can find more information on these scripts in the
882 "<link linkend='pushing-a-change-upstream'>Using
883 Scripts to Push a Change Upstream and Request a Pull</link>" section.
884 </para></listitem>
885 <listitem><para><emphasis>Patch Workflow:</emphasis> This workflow allows you to notify the
886 maintainer through an email that you have a change (or patch) you would like considered
887 for the "master" branch of the Git repository.
888 To send this type of change you format the patch and then send the email using the Git commands
889 <filename>git format-patch</filename> and <filename>git send-email</filename>.
890 You can find information on how to submit changes
891 later in this chapter.</para></listitem>
892 </itemizedlist>
893 </para>
894</section>
895
896<section id='tracking-bugs'>
897 <title>Tracking Bugs</title>
898
899 <para>
900 The Yocto Project uses its own implementation of
901 <ulink url='http://www.bugzilla.org/about/'>Bugzilla</ulink> to track bugs.
902 Implementations of Bugzilla work well for group development because they track bugs and code
903 changes, can be used to communicate changes and problems with developers, can be used to
904 submit and review patches, and can be used to manage quality assurance.
905 The home page for the Yocto Project implementation of Bugzilla is
906 <ulink url='&YOCTO_BUGZILLA_URL;'>&YOCTO_BUGZILLA_URL;</ulink>.
907 </para>
908
909 <para>
910 Sometimes it is helpful to submit, investigate, or track a bug against the Yocto Project itself
911 such as when discovering an issue with some component of the build system that acts contrary
912 to the documentation or your expectations.
913 Following is the general procedure for submitting a new bug using the Yocto Project
914 Bugzilla.
915 You can find more information on defect management, bug tracking, and feature request
916 processes all accomplished through the Yocto Project Bugzilla on the wiki page
917 <ulink url='&YOCTO_WIKI_URL;/wiki/Bugzilla_Configuration_and_Bug_Tracking'>here</ulink>.
918 <orderedlist>
919 <listitem><para>Always use the Yocto Project implementation of Bugzilla to submit
920 a bug.</para></listitem>
921 <listitem><para>When submitting a new bug, be sure to choose the appropriate
922 Classification, Product, and Component for which the issue was found.
923 Defects for Yocto Project fall into one of six classifications: Yocto Project
924 Components, Infrastructure, Build System &amp; Metadata, Documentation,
925 QA/Testing, and Runtime.
926 Each of these Classifications break down into multiple Products and, in some
927 cases, multiple Components.</para></listitem>
928 <listitem><para>Use the bug form to choose the correct Hardware and Architecture
929 for which the bug applies.</para></listitem>
930 <listitem><para>Indicate the Yocto Project version you were using when the issue
931 occurred.</para></listitem>
932 <listitem><para>Be sure to indicate the Severity of the bug.
933 Severity communicates how the bug impacted your work.</para></listitem>
934 <listitem><para>Provide a brief summary of the issue.
935 Try to limit your summary to just a line or two and be sure to capture the
936 essence of the issue.</para></listitem>
937 <listitem><para>Provide a detailed description of the issue.
938 You should provide as much detail as you can about the context, behavior, output,
939 and so forth that surround the issue.
940 You can even attach supporting files for output or log by using the "Add an attachment"
941 button.</para></listitem>
942 <listitem><para>Submit the bug by clicking the "Submit Bug" button.</para></listitem>
943 </orderedlist>
944 </para>
945</section>
946
947<section id='how-to-submit-a-change'>
948 <title>How to Submit a Change</title>
949
950 <para>
951 Contributions to the Yocto Project and OpenEmbedded are very welcome.
952 Because the system is extremely configurable and flexible, we recognize that developers
953 will want to extend, configure or optimize it for their specific uses.
954 You should send patches to the appropriate mailing list so that they
955 can be reviewed and merged by the appropriate maintainer.
956 For a list of the Yocto Project and related mailing lists, see the
957 "<ulink url='&YOCTO_DOCS_REF_URL;#resources-mailinglist'>Mailing lists</ulink>" section in
958 the Yocto Project Reference Manual.
959 </para>
960
961 <para>
962 The following is some guidance on which mailing list to use for what type of change:
963 <itemizedlist>
964 <listitem><para>For changes to the core metadata, send your patch to the
965 <ulink url='&OE_LISTS_URL;/listinfo/openembedded-core'>openembedded-core</ulink> mailing list.
966 For example, a change to anything under the <filename>meta</filename> or
967 <filename>scripts</filename> directories
968 should be sent to this mailing list.</para></listitem>
969 <listitem><para>For changes to BitBake (anything under the <filename>bitbake</filename>
970 directory), send your patch to the
971 <ulink url='&OE_LISTS_URL;/listinfo/bitbake-devel'>bitbake-devel</ulink> mailing list.</para></listitem>
972 <listitem><para>For changes to <filename>meta-yocto</filename>, send your patch to the
973 <ulink url='&YOCTO_LISTS_URL;/listinfo/poky'>poky</ulink> mailing list.</para></listitem>
974 <listitem><para>For changes to other layers hosted on
975 <filename>yoctoproject.org</filename> (unless the
976 layer's documentation specifies otherwise), tools, and Yocto Project
977 documentation, use the
978 <ulink url='&YOCTO_LISTS_URL;/listinfo/yocto'>yocto</ulink> mailing list.</para></listitem>
979 <listitem><para>For additional recipes that do not fit into the core metadata,
980 you should determine which layer the recipe should go into and submit the
981 change in the manner recommended by the documentation (e.g. README) supplied
982 with the layer. If in doubt, please ask on the
983 <ulink url='&YOCTO_LISTS_URL;/listinfo/yocto'>yocto</ulink> or
984 <ulink url='&OE_LISTS_URL;/listinfo/openembedded-devel'>openembedded-devel</ulink>
985 mailing lists.</para></listitem>
986 </itemizedlist>
987 </para>
988
989 <para>
990 When you send a patch, be sure to include a "Signed-off-by:"
991 line in the same style as required by the Linux kernel.
992 Adding this line signifies that you, the submitter, have agreed to the Developer's Certificate of Origin 1.1
993 as follows:
994 <literallayout class='monospaced'>
995 Developer's Certificate of Origin 1.1
996
997 By making a contribution to this project, I certify that:
998
999 (a) The contribution was created in whole or in part by me and I
1000 have the right to submit it under the open source license
1001 indicated in the file; or
1002
1003 (b) The contribution is based upon previous work that, to the best
1004 of my knowledge, is covered under an appropriate open source
1005 license and I have the right under that license to submit that
1006 work with modifications, whether created in whole or in part
1007 by me, under the same open source license (unless I am
1008 permitted to submit under a different license), as indicated
1009 in the file; or
1010
1011 (c) The contribution was provided directly to me by some other
1012 person who certified (a), (b) or (c) and I have not modified
1013 it.
1014
1015 (d) I understand and agree that this project and the contribution
1016 are public and that a record of the contribution (including all
1017 personal information I submit with it, including my sign-off) is
1018 maintained indefinitely and may be redistributed consistent with
1019 this project or the open source license(s) involved.
1020 </literallayout>
1021 </para>
1022
1023 <para>
1024 In a collaborative environment, it is necessary to have some sort of standard
1025 or method through which you submit changes.
1026 Otherwise, things could get quite chaotic.
1027 One general practice to follow is to make small, controlled changes.
1028 Keeping changes small and isolated aids review, makes merging/rebasing easier
1029 and keeps the change history clean when anyone needs to refer to it in future.
1030 </para>
1031
1032 <para>
1033 When you make a commit, you must follow certain standards established by the
1034 OpenEmbedded and Yocto Project development teams.
1035 For each commit, you must provide a single-line summary of the change and you
1036 should almost always provide a more detailed description of what you did (i.e.
1037 the body of the commit message).
1038 The only exceptions for not providing a detailed description would be if your
1039 change is a simple, self-explanatory change that needs no further description
1040 beyond the summary.
1041 Here are the guidelines for composing a commit message:
1042 <itemizedlist>
1043 <listitem><para>Provide a single-line, short summary of the change.
1044 This summary is typically viewable in the "shortlist" of changes.
1045 Thus, providing something short and descriptive that gives the reader
1046 a summary of the change is useful when viewing a list of many commits.
1047 This should be prefixed by the recipe name (if changing a recipe), or
1048 else the short form path to the file being changed.
1049 </para></listitem>
1050 <listitem><para>For the body of the commit message, provide detailed information
1051 that describes what you changed, why you made the change, and the approach
1052 you used. It may also be helpful if you mention how you tested the change.
1053 Provide as much detail as you can in the body of the commit message.
1054 </para></listitem>
1055 <listitem><para>If the change addresses a specific bug or issue that is
1056 associated with a bug-tracking ID, include a reference to that ID in
1057 your detailed description.
1058 For example, the Yocto Project uses a specific convention for bug
1059 references - any commit that addresses a specific bug should include the
1060 bug ID in the description (typically at the beginning) as follows:
1061 <literallayout class='monospaced'>
1062 [YOCTO #&lt;bug-id&gt;]
1063
1064 &lt;detailed description of change&gt;
1065 </literallayout></para></listitem>
1066 Where &lt;bug-id&gt; is replaced with the specific bug ID from the
1067 Yocto Project Bugzilla instance.
1068 </itemizedlist>
1069 </para>
1070
1071 <para>
1072 You can find more guidance on creating well-formed commit messages at this OpenEmbedded
1073 wiki page:
1074 <ulink url='&OE_HOME_URL;/wiki/Commit_Patch_Message_Guidelines'></ulink>.
1075 </para>
1076
1077 <para>
1078 Following are general instructions for both pushing changes upstream and for submitting
1079 changes as patches.
1080 </para>
1081
1082 <section id='pushing-a-change-upstream'>
1083 <title>Using Scripts to Push a Change Upstream and Request a Pull</title>
1084
1085 <para>
1086 The basic flow for pushing a change to an upstream "contrib" Git repository is as follows:
1087 <itemizedlist>
1088 <listitem><para>Make your changes in your local Git repository.</para></listitem>
1089 <listitem><para>Stage your changes by using the <filename>git add</filename>
1090 command on each file you changed.</para></listitem>
1091 <listitem><para>Commit the change by using the <filename>git commit</filename>
1092 command and push it to the "contrib" repository.
1093 Be sure to provide a commit message that follows the project’s commit message standards
1094 as described earlier.</para></listitem>
1095 <listitem><para>Notify the maintainer that you have pushed a change by making a pull
1096 request.
1097 The Yocto Project provides two scripts that conveniently let you generate and send
1098 pull requests to the Yocto Project.
1099 These scripts are <filename>create-pull-request</filename> and
1100 <filename>send-pull-request</filename>.
1101 You can find these scripts in the <filename>scripts</filename> directory
1102 within the <link linkend='source-directory'>Source Directory</link>.</para>
1103 <para>Using these scripts correctly formats the requests without introducing any
1104 whitespace or HTML formatting.
1105 The maintainer that receives your patches needs to be able to save and apply them
1106 directly from your emails.
1107 Using these scripts is the preferred method for sending patches.</para>
1108 <para>For help on using these scripts, simply provide the
1109 <filename>-h</filename> argument as follows:
1110 <literallayout class='monospaced'>
1111 $ ~/poky/scripts/create-pull-request -h
1112 $ ~/poky/scripts/send-pull-request -h
1113 </literallayout></para></listitem>
1114 </itemizedlist>
1115 </para>
1116
1117 <para>
1118 You can find general Git information on how to push a change upstream in the
1119 <ulink url='http://book.git-scm.com/3_distributed_workflows.html'>Git Community Book</ulink>.
1120 </para>
1121 </section>
1122
1123 <section id='submitting-a-patch'>
1124 <title>Using Email to Submit a Patch</title>
1125
1126 <para>
1127 You can submit patches without using the <filename>create-pull-request</filename> and
1128 <filename>send-pull-request</filename> scripts described in the previous section.
1129 Keep in mind, the preferred method is to use the scripts, however.
1130 </para>
1131
1132 <para>
1133 Depending on the components changed, you need to submit the email to a specific
1134 mailing list.
1135 For some guidance on which mailing list to use, see the list in the
1136 "<link linkend='how-to-submit-a-change'>How to Submit a Change</link>" section
1137 earlier in this manual.
1138 For a description of the available mailing lists, see
1139 "<ulink url='&YOCTO_DOCS_REF_URL;#resources-mailinglist'>Mailing Lists</ulink>"
1140 section in the Yocto Project Reference Manual.
1141 </para>
1142
1143 <para>
1144 Here is the general procedure on how to submit a patch through email without using the
1145 scripts:
1146 <itemizedlist>
1147 <listitem><para>Make your changes in your local Git repository.</para></listitem>
1148 <listitem><para>Stage your changes by using the <filename>git add</filename>
1149 command on each file you changed.</para></listitem>
1150 <listitem><para>Commit the change by using the
1151 <filename>git commit --signoff</filename> command.
1152 Using the <filename>--signoff</filename> option identifies you as the person
1153 making the change and also satisfies the Developer's Certificate of
1154 Origin (DCO) shown earlier.</para>
1155 <para>When you form a commit you must follow certain standards established by the
1156 Yocto Project development team.
1157 See the earlier section
1158 "<link linkend='how-to-submit-a-change'>How to Submit a Change</link>"
1159 for Yocto Project commit message standards.</para></listitem>
1160 <listitem><para>Format the commit into an email message.
1161 To format commits, use the <filename>git format-patch</filename> command.
1162 When you provide the command, you must include a revision list or a number of patches
1163 as part of the command.
1164 For example, these two commands each take the most recent single commit and
1165 format it as an email message in the current directory:
1166 <literallayout class='monospaced'>
1167 $ git format-patch -1
1168 $ git format-patch HEAD~
1169 </literallayout></para>
1170 <para>After the command is run, the current directory contains a
1171 numbered <filename>.patch</filename> file for the commit.</para>
1172 <para>If you provide several commits as part of the command,
1173 the <filename>git format-patch</filename> command produces a numbered
1174 series of files in the current directory – one for each commit.
1175 If you have more than one patch, you should also use the
1176 <filename>--cover</filename> option with the command, which generates a
1177 cover letter as the first "patch" in the series.
1178 You can then edit the cover letter to provide a description for
1179 the series of patches.
1180 For information on the <filename>git format-patch</filename> command,
1181 see <filename>GIT_FORMAT_PATCH(1)</filename> displayed using the
1182 <filename>man git-format-patch</filename> command.</para>
1183 <note>If you are or will be a frequent contributor to the Yocto Project
1184 or to OpenEmbedded, you might consider requesting a contrib area and the
1185 necessary associated rights.</note></listitem>
1186 <listitem><para>Import the files into your mail client by using the
1187 <filename>git send-email</filename> command.
1188 <note>In order to use <filename>git send-email</filename>, you must have the
1189 the proper Git packages installed.
1190 For Ubuntu and Fedora the package is <filename>git-email</filename>.</note></para>
1191 <para>The <filename>git send-email</filename> command sends email by using a local
1192 or remote Mail Transport Agent (MTA) such as
1193 <filename>msmtp</filename>, <filename>sendmail</filename>, or through a direct
1194 <filename>smtp</filename> configuration in your Git <filename>config</filename>
1195 file.
1196 If you are submitting patches through email only, it is very important
1197 that you submit them without any whitespace or HTML formatting that
1198 either you or your mailer introduces.
1199 The maintainer that receives your patches needs to be able to save and
1200 apply them directly from your emails.
1201 A good way to verify that what you are sending will be applicable by the
1202 maintainer is to do a dry run and send them to yourself and then
1203 save and apply them as the maintainer would.</para>
1204 <para>The <filename>git send-email</filename> command is the preferred method
1205 for sending your patches since there is no risk of compromising whitespace
1206 in the body of the message, which can occur when you use your own mail client.
1207 The command also has several options that let you
1208 specify recipients and perform further editing of the email message.
1209 For information on how to use the <filename>git send-email</filename> command,
1210 use the <filename>man git-send-email</filename> command.</para></listitem>
1211 </itemizedlist>
1212 </para>
1213 </section>
1214</section>
1215</chapter>
1216<!--
1217vim: expandtab tw=80 ts=4
1218-->
generated by cgit v1.2.3-54-g00ecf (git 2.39.0) at 2024-05-10 05:19:35 +0000