summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorScott Rifenbark <scott.m.rifenbark@intel.com>2014-03-17 20:36:17 (GMT)
committerRichard Purdie <richard.purdie@linuxfoundation.org>2014-03-25 12:29:41 (GMT)
commitdd72756230788dcd88ab14ab32757dd427d67e78 (patch)
tree8c5c45d6e56990aa27d8ed7950f2c422d4b13501
parentcee847acf000d0b067eff1a5873c69ebd826014a (diff)
downloadpoky-dd72756230788dcd88ab14ab32757dd427d67e78.tar.gz
dev-manual: Read-through edits to Chapter 3.
The changes are a result of a detailed read-through prior to releasing YP 1.6. The changes are varied and random. (From yocto-docs rev: 04c09abf96a04c3ffeea8cdf7be8e1bb1b9055c6) Signed-off-by: Scott Rifenbark <scott.m.rifenbark@intel.com> Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
-rw-r--r--documentation/dev-manual/dev-manual-newbie.xml263
1 files changed, 159 insertions, 104 deletions
diff --git a/documentation/dev-manual/dev-manual-newbie.xml b/documentation/dev-manual/dev-manual-newbie.xml
index eab563f..77c14a6 100644
--- a/documentation/dev-manual/dev-manual-newbie.xml
+++ b/documentation/dev-manual/dev-manual-newbie.xml
@@ -171,7 +171,7 @@
171 pool similarly to how the developer workstations 171 pool similarly to how the developer workstations
172 contribute. 172 contribute.
173 For information, see the 173 For information, see the
174 <link linkend='best-practices-autobuilders'>Autobuilders</link> 174 "<link linkend='best-practices-autobuilders'>Autobuilders</link>"
175 section.</para></listitem> 175 section.</para></listitem>
176 <listitem><para>Build stand-alone tarballs that contain 176 <listitem><para>Build stand-alone tarballs that contain
177 "missing" system requirements if for some reason 177 "missing" system requirements if for some reason
@@ -184,8 +184,8 @@
184 on most distributions.</para></listitem> 184 on most distributions.</para></listitem>
185 <listitem><para>Use a small number of shared, 185 <listitem><para>Use a small number of shared,
186 high performance systems for testing purposes 186 high performance systems for testing purposes
187 (e.g. dual six core Xeons with 24GB RAM and plenty of 187 (e.g. dual, six-core Xeons with 24 Gbytes of RAM
188 disk space). 188 and plenty of disk space).
189 Developers can use these systems for wider, more 189 Developers can use these systems for wider, more
190 extensive testing while they continue to develop 190 extensive testing while they continue to develop
191 locally using their primary development system. 191 locally using their primary development system.
@@ -222,10 +222,8 @@
222 allows you to work remotely, and then connects back to the 222 allows you to work remotely, and then connects back to the
223 infrastructure. 223 infrastructure.
224 <note> 224 <note>
225 For information about BitBake and SCMs, see the 225 For information about BitBake, see the
226 BitBake manual located in the 226 <ulink url='&YOCTO_DOCS_BB_URL;'>BitBake User Manual</ulink>.
227 <filename>bitbake/doc/manual</filename> directory of the
228 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
229 </note> 227 </note>
230 </para> 228 </para>
231 229
@@ -238,7 +236,7 @@
238 being used to generate the web interface that lets you view the 236 being used to generate the web interface that lets you view the
239 repositories. 237 repositories.
240 The <filename>gitolite</filename> software identifies users 238 The <filename>gitolite</filename> software identifies users
241 using <filename>ssh</filename> keys and allows branch-based 239 using SSH keys and allows branch-based
242 access controls to repositories that you can control as little 240 access controls to repositories that you can control as little
243 or as much as necessary. 241 or as much as necessary.
244 </para> 242 </para>
@@ -298,8 +296,8 @@
298 <listitem><para>Allows triggering of automated image booting 296 <listitem><para>Allows triggering of automated image booting
299 and testing under the QuickEMUlator (QEMU). 297 and testing under the QuickEMUlator (QEMU).
300 </para></listitem> 298 </para></listitem>
301 <listitem><para>Supports incremental build testing and from 299 <listitem><para>Supports incremental build testing and
302 scratch builds.</para></listitem> 300 from-scratch builds.</para></listitem>
303 <listitem><para>Shares output that allows developer 301 <listitem><para>Shares output that allows developer
304 testing and historical regression investigation. 302 testing and historical regression investigation.
305 </para></listitem> 303 </para></listitem>
@@ -365,14 +363,18 @@
365 See the "<link linkend='understanding-and-creating-layers'>Understanding 363 See the "<link linkend='understanding-and-creating-layers'>Understanding
366 and Creating Layers</link>" section for more information on 364 and Creating Layers</link>" section for more information on
367 layers.</para></listitem> 365 layers.</para></listitem>
368 <listitem><para>Separate the project's Metadata and code by using 366 <listitem><para>
367 Separate the project's Metadata and code by using
369 separate Git repositories. 368 separate Git repositories.
370 See the "<link linkend='yocto-project-repositories'>Yocto Project 369 See the
371 Source Repositories</link>" section for information on these 370 "<link linkend='yocto-project-repositories'>Yocto Project Source Repositories</link>"
372 repositories. 371 section for information on these repositories.
373 See the "<link linkend='getting-setup'>Getting Set Up</link>" section 372 See the
374 for information on how to set up various Yocto Project related 373 "<link linkend='getting-setup'>Getting Set Up</link>"
375 Git repositories.</para></listitem> 374 section for information on how to set up local Git
375 repositories for related upstream Yocto Project
376 Git repositories.
377 </para></listitem>
376 <listitem><para>Set up the directory for the shared state cache 378 <listitem><para>Set up the directory for the shared state cache
377 (<ulink url='&YOCTO_DOCS_REF_URL;#var-SSTATE_DIR'><filename>SSTATE_DIR</filename></ulink>) 379 (<ulink url='&YOCTO_DOCS_REF_URL;#var-SSTATE_DIR'><filename>SSTATE_DIR</filename></ulink>)
378 where it makes sense. 380 where it makes sense.
@@ -389,7 +391,7 @@
389 See the "<link linkend='how-to-submit-a-change'>How to Submit a Change</link>" 391 See the "<link linkend='how-to-submit-a-change'>How to Submit a Change</link>"
390 section.</para></listitem> 392 section.</para></listitem>
391 <listitem><para>Send changes to the core sooner than later 393 <listitem><para>Send changes to the core sooner than later
392 as others likely run into the same issues. 394 as others are likely to run into the same issues.
393 For some guidance on mailing lists to use, see the list in the 395 For some guidance on mailing lists to use, see the list in the
394 "<link linkend='how-to-submit-a-change'>How to Submit a Change</link>" 396 "<link linkend='how-to-submit-a-change'>How to Submit a Change</link>"
395 section. 397 section.
@@ -415,7 +417,9 @@
415 From the interface, you can click on any particular item in the "Name" 417 From the interface, you can click on any particular item in the "Name"
416 column and see the URL at the bottom of the page that you need to clone 418 column and see the URL at the bottom of the page that you need to clone
417 a Git repository for that particular item. 419 a Git repository for that particular item.
418 Having a local Git repository of the Source Directory (poky) allows 420 Having a local Git repository of the
421 <link linkend='source-directory'>Source Directory</link>, which is
422 usually named "poky", allows
419 you to make changes, contribute to the history, and ultimately enhance 423 you to make changes, contribute to the history, and ultimately enhance
420 the Yocto Project's tools, Board Support Packages, and so forth. 424 the Yocto Project's tools, Board Support Packages, and so forth.
421 </para> 425 </para>
@@ -447,9 +451,9 @@
447 <imagedata fileref="figures/source-repos.png" align="center" width="6in" depth="4in" /> 451 <imagedata fileref="figures/source-repos.png" align="center" width="6in" depth="4in" />
448 </para></listitem> 452 </para></listitem>
449 <listitem><para><anchor id='index-downloads' /><emphasis><ulink url='&YOCTO_DL_URL;/releases/'>Index of /releases:</ulink></emphasis> 453 <listitem><para><anchor id='index-downloads' /><emphasis><ulink url='&YOCTO_DL_URL;/releases/'>Index of /releases:</ulink></emphasis>
450 This area contains index releases such as 454 This is an index of releases such as
451 the <trademark class='trade'>Eclipse</trademark> 455 the <trademark class='trade'>Eclipse</trademark>
452 Yocto Plug-in, miscellaneous support, poky, pseudo, installers for cross-development toolchains, 456 Yocto Plug-in, miscellaneous support, Poky, Pseudo, installers for cross-development toolchains,
453 and all released versions of Yocto Project in the form of images or tarballs. 457 and all released versions of Yocto Project in the form of images or tarballs.
454 Downloading and extracting these files does not produce a local copy of the 458 Downloading and extracting these files does not produce a local copy of the
455 Git repository but rather a snapshot of a particular release or image.</para> 459 Git repository but rather a snapshot of a particular release or image.</para>
@@ -494,11 +498,11 @@
494 "<link linkend='using-bbappend-files'>Using .bbappend Files</link>" section. 498 "<link linkend='using-bbappend-files'>Using .bbappend Files</link>" section.
495 </para></listitem> 499 </para></listitem>
496 <listitem><para id='bitbake-term'><emphasis>BitBake:</emphasis> 500 <listitem><para id='bitbake-term'><emphasis>BitBake:</emphasis>
497 The task executor and scheduler used by 501 The task executor and scheduler used by the OpenEmbedded build
498 the OpenEmbedded build system to build images. 502 system to build images.
499 For more information on BitBake, see the BitBake documentation 503 For more information on BitBake, see the
500 in the <filename>bitbake/doc/manual</filename> directory of the 504 <ulink url='&YOCTO_DOCS_BB_URL;'>BitBake User Manual</ulink>.
501 <link linkend='source-directory'>Source Directory</link>.</para></listitem> 505 </para></listitem>
502 <listitem> 506 <listitem>
503 <para id='build-directory'><emphasis>Build Directory:</emphasis> 507 <para id='build-directory'><emphasis>Build Directory:</emphasis>
504 This term refers to the area used by the OpenEmbedded build system for builds. 508 This term refers to the area used by the OpenEmbedded build system for builds.
@@ -533,8 +537,9 @@
533 $ cd $HOME 537 $ cd $HOME
534 $ source poky/&OE_INIT_FILE; test-builds 538 $ source poky/&OE_INIT_FILE; test-builds
535 </literallayout></para></listitem> 539 </literallayout></para></listitem>
536 <listitem><para>Provide a directory path and 540 <listitem><para>
537 specifically name the build directory. 541 Provide a directory path and
542 specifically name the Build Directory.
538 Any intermediate folders in the pathname must 543 Any intermediate folders in the pathname must
539 exist. 544 exist.
540 This next example creates a Build Directory named 545 This next example creates a Build Directory named
@@ -557,23 +562,31 @@
557 <listitem><para><emphasis>Classes:</emphasis> Files that provide for logic encapsulation 562 <listitem><para><emphasis>Classes:</emphasis> Files that provide for logic encapsulation
558 and inheritance so that commonly used patterns can be defined once and then easily used 563 and inheritance so that commonly used patterns can be defined once and then easily used
559 in multiple recipes. 564 in multiple recipes.
565 For reference information on the Yocto Project classes, see the
566 "<ulink url='&YOCTO_DOCS_REF_URL;#ref-classes'>Classes</ulink>" chapter of the
567 Yocto Project Reference Manual.
560 Class files end with the <filename>.bbclass</filename> filename extension. 568 Class files end with the <filename>.bbclass</filename> filename extension.
561 </para></listitem> 569 </para></listitem>
562 <listitem><para><emphasis>Configuration File:</emphasis> Configuration information in various 570 <listitem><para><emphasis>Configuration File:</emphasis>
563 <filename>.conf</filename> files provides global definitions of variables. 571 Configuration information in various <filename>.conf</filename>
564 The <filename>conf/local.conf</filename> configuration file in the 572 files provides global definitions of variables.
573 The <filename>conf/local.conf</filename> configuration file in
574 the
565 <link linkend='build-directory'>Build Directory</link> 575 <link linkend='build-directory'>Build Directory</link>
566 contains user-defined variables that affect each build. 576 contains user-defined variables that affect every build.
567 The <filename>meta-yocto/conf/distro/poky.conf</filename> configuration file 577 The <filename>meta-yocto/conf/distro/poky.conf</filename>
568 defines Yocto "distro" configuration 578 configuration file defines Yocto "distro" configuration
569 variables used only when building with this policy. 579 variables used only when building with this policy.
570 Machine configuration files, which 580 Machine configuration files, which
571 are located throughout the 581 are located throughout the
572 <link linkend='source-directory'>Source Directory</link>, define 582 <link linkend='source-directory'>Source Directory</link>, define
573 variables for specific hardware and are only used when building for that target 583 variables for specific hardware and are only used when building
574 (e.g. the <filename>machine/beagleboard.conf</filename> configuration file defines 584 for that target (e.g. the
575 variables for the Texas Instruments ARM Cortex-A8 development board). 585 <filename>machine/beagleboard.conf</filename> configuration
576 Configuration files end with a <filename>.conf</filename> filename extension. 586 file defines variables for the Texas Instruments ARM Cortex-A8
587 development board).
588 Configuration files end with a <filename>.conf</filename>
589 filename extension.
577 </para></listitem> 590 </para></listitem>
578 <listitem><para id='cross-development-toolchain'> 591 <listitem><para id='cross-development-toolchain'>
579 <emphasis>Cross-Development Toolchain:</emphasis> 592 <emphasis>Cross-Development Toolchain:</emphasis>
@@ -611,10 +624,11 @@
611 <ulink url='&YOCTO_DOCS_ADT_URL;'>Yocto Project 624 <ulink url='&YOCTO_DOCS_ADT_URL;'>Yocto Project
612 Application Developer's Guide</ulink>. 625 Application Developer's Guide</ulink>.
613 </para></listitem> 626 </para></listitem>
614 <listitem><para><emphasis>Image:</emphasis> An image is the result produced when 627 <listitem><para><emphasis>Image:</emphasis>
615 BitBake processes a given collection of recipes and related Metadata. 628 An image is the result produced when BitBake processes a given
616 Images are the binary output that run on specific hardware or QEMU 629 collection of recipes and related Metadata.
617 and for specific use cases. 630 Images are the binary output that run on specific hardware or
631 QEMU and are used for specific use-cases.
618 For a list of the supported image types that the Yocto Project provides, see the 632 For a list of the supported image types that the Yocto Project provides, see the
619 "<ulink url='&YOCTO_DOCS_REF_URL;#ref-images'>Images</ulink>" 633 "<ulink url='&YOCTO_DOCS_REF_URL;#ref-images'>Images</ulink>"
620 chapter in the Yocto Project Reference Manual.</para></listitem> 634 chapter in the Yocto Project Reference Manual.</para></listitem>
@@ -640,9 +654,12 @@
640 with OpenEmbedded (OE) that is shared between OE and the Yocto Project. 654 with OpenEmbedded (OE) that is shared between OE and the Yocto Project.
641 This Metadata is found in the <filename>meta</filename> directory of the 655 This Metadata is found in the <filename>meta</filename> directory of the
642 <link linkend='source-directory'>Source Directory</link>.</para></listitem> 656 <link linkend='source-directory'>Source Directory</link>.</para></listitem>
643 <listitem><para><emphasis>Package:</emphasis> In the context of the Yocto Project, 657 <listitem><para><emphasis>Package:</emphasis>
644 this term refers to the packaged output from a baked recipe. 658 In the context of the Yocto Project, this term refers a
645 A package is generally the compiled binaries produced from the recipe's sources. 659 recipe's packaged output produced by BitBake (i.e. a
660 "baked recipe").
661 A package is generally the compiled binaries produced from the
662 recipe's sources.
646 You "bake" something by running it through BitBake.</para> 663 You "bake" something by running it through BitBake.</para>
647 <para>It is worth noting that the term "package" can, in general, have subtle 664 <para>It is worth noting that the term "package" can, in general, have subtle
648 meanings. For example, the packages referred to in the 665 meanings. For example, the packages referred to in the
@@ -673,24 +690,35 @@
673 by OpenedHand. With OpenedHand, poky was developed off of the existing OpenEmbedded 690 by OpenedHand. With OpenedHand, poky was developed off of the existing OpenEmbedded
674 build system becoming a build system for embedded images. 691 build system becoming a build system for embedded images.
675 After Intel Corporation acquired OpenedHand, the project poky became the basis for 692 After Intel Corporation acquired OpenedHand, the project poky became the basis for
676 the Yocto Project's build system. 693 the Yocto Project's build system.</para>
694 <para>
677 Within the Yocto Project source repositories, <filename>poky</filename> 695 Within the Yocto Project source repositories, <filename>poky</filename>
678 exists as a separate Git repository 696 exists as a separate Git repository
679 that can be cloned to yield a local copy on the host system. 697 that can be cloned to yield a local copy on the host system.
680 Thus, "poky" can refer to the local copy of the Source Directory used to develop within 698 Thus, "poky" can refer to the local copy of the Source Directory used to develop within
681 the Yocto Project.</para></listitem> 699 the Yocto Project.</para></listitem>
682 <listitem><para><emphasis>Recipe:</emphasis> A set of instructions for building packages. 700 <listitem><para><emphasis>Recipe:</emphasis>
683 A recipe describes where you get source code and which patches to apply. 701 A set of instructions for building packages.
684 Recipes describe dependencies for libraries or for other recipes, and they 702 A recipe describes where you get source code and which patches
685 also contain configuration and compilation options. 703 to apply.
686 Recipes contain the logical unit of execution, the software/images to build, and 704 Recipes describe dependencies for libraries or for other
687 use the <filename>.bb</filename> file extension.</para></listitem> 705 recipes, and they also contain configuration and compilation
706 options.
707 Recipes contain the logical unit of execution, the software
708 to build, the images to build, and use the
709 <filename>.bb</filename> file extension.
710 </para></listitem>
688 <listitem> 711 <listitem>
689 <para id='source-directory'><emphasis>Source Directory:</emphasis> 712 <para id='source-directory'><emphasis>Source Directory:</emphasis>
690 This term refers to the directory structure created as a result 713 This term refers to the directory structure created as a result
691 of creating a local copy of the <filename>poky</filename> Git 714 of creating a local copy of the <filename>poky</filename> Git
692 repository <filename>git://git.yoctoproject.org/poky</filename> 715 repository <filename>git://git.yoctoproject.org/poky</filename>
693 or expanding a released <filename>poky</filename> tarball. 716 or expanding a released <filename>poky</filename> tarball.
717 <note>
718 Creating a local copy of the <filename>poky</filename>
719 Git repository is the recommended method for setting up
720 your Source Directory.
721 </note>
694 Sometimes you might hear the term "poky directory" used to refer 722 Sometimes you might hear the term "poky directory" used to refer
695 to this directory structure. 723 to this directory structure.
696 <note> 724 <note>
@@ -708,12 +736,12 @@
708 736
709 <para>When you create a local copy of the Git repository, you 737 <para>When you create a local copy of the Git repository, you
710 can name the repository anything you like. 738 can name the repository anything you like.
711 Throughout much of the documentation, <filename>poky</filename> 739 Throughout much of the documentation, "poky"
712 is used as the name of the top-level folder of the local copy of 740 is used as the name of the top-level folder of the local copy of
713 the poky Git repository. 741 the poky Git repository.
714 So, for example, cloning the <filename>poky</filename> Git 742 So, for example, cloning the <filename>poky</filename> Git
715 repository results in a local Git repository whose top-level 743 repository results in a local Git repository whose top-level
716 folder is also named <filename>poky</filename>.</para> 744 folder is also named "poky".</para>
717 745
718 <para>While it is not recommended that you use tarball expansion 746 <para>While it is not recommended that you use tarball expansion
719 to setup the Source Directory, if you do, the top-level 747 to setup the Source Directory, if you do, the top-level
@@ -815,18 +843,23 @@
815 for a standard format for communicating the components, licenses, and copyrights 843 for a standard format for communicating the components, licenses, and copyrights
816 associated with a software package. 844 associated with a software package.
817 <ulink url='http://opensource.org'>OSI</ulink> is a corporation dedicated to the Open Source 845 <ulink url='http://opensource.org'>OSI</ulink> is a corporation dedicated to the Open Source
818 Definition and the effort for reviewing and approving licenses that are OSD-conformant. 846 Definition and the effort for reviewing and approving licenses that
847 conform to the Open Source Definition (OSD).
819 </para> 848 </para>
820 849
821 <para> 850 <para>
822 You can find a list of the combined SPDX and OSI licenses that the Yocto Project uses 851 You can find a list of the combined SPDX and OSI licenses that the
823 <ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi/poky/tree/meta/files/common-licenses'>here</ulink>. 852 Yocto Project uses in the
853 <filename>meta/files/common-licenses</filename> directory in your
854 <link linkend='source-directory'>Source Directory</link>.
824 </para> 855 </para>
825 856
826 <para> 857 <para>
827 For information that can help you to maintain compliance with various open source licensing 858 For information that can help you maintain compliance with various
828 during the lifecycle of a product created using the Yocto Project, see the 859 open source licensing during the lifecycle of a product created using
829 "<link linkend='maintaining-open-source-license-compliance-during-your-products-lifecycle'>Maintaining Open Source License Compliance During Your Product's Lifecycle</link>" section. 860 the Yocto Project, see the
861 "<link linkend='maintaining-open-source-license-compliance-during-your-products-lifecycle'>Maintaining Open Source License Compliance During Your Product's Lifecycle</link>"
862 section.
830 </para> 863 </para>
831</section> 864</section>
832 865
@@ -889,12 +922,14 @@
889 </para> 922 </para>
890 923
891 <para> 924 <para>
892 It is important to understand that Git tracks content change and not files. 925 It is important to understand that Git tracks content change and
926 not files.
893 Git uses "branches" to organize different development efforts. 927 Git uses "branches" to organize different development efforts.
894 For example, the <filename>poky</filename> repository has 928 For example, the <filename>poky</filename> repository has
895 <filename>denzil</filename>, <filename>danny</filename>, 929 <filename>denzil</filename>, <filename>danny</filename>,
896 <filename>dylan</filename>, <filename>dora</filename>, 930 <filename>dylan</filename>, <filename>dora</filename>,
897 and <filename>master</filename> branches among others. 931 <filename>daisy</filename>, and <filename>master</filename> branches
932 among others.
898 You can see all the branches by going to 933 You can see all the branches by going to
899 <ulink url='&YOCTO_GIT_URL;/cgit.cgi/poky/'></ulink> and 934 <ulink url='&YOCTO_GIT_URL;/cgit.cgi/poky/'></ulink> and
900 clicking on the 935 clicking on the
@@ -928,37 +963,38 @@
928 </literallayout> 963 </literallayout>
929 In this example, the name of the top-level directory of your local 964 In this example, the name of the top-level directory of your local
930 <link linkend='source-directory'>Source Directory</link> 965 <link linkend='source-directory'>Source Directory</link>
931 is <filename>poky</filename>, 966 is "poky" and the name of that local working area (local branch)
932 and the name of that local working area (local branch) you just 967 you just created and checked out is "&DISTRO_NAME;".
933 created and checked out is <filename>&DISTRO_NAME;</filename>.
934 The files in your local repository now reflect the same files that 968 The files in your local repository now reflect the same files that
935 are in the <filename>&DISTRO_NAME;</filename> development 969 are in the "&DISTRO_NAME;" development branch of the
936 branch of the Yocto Project's <filename>poky</filename> 970 Yocto Project's "poky" upstream repository.
937 upstream repository.
938 It is important to understand that when you create and checkout a 971 It is important to understand that when you create and checkout a
939 local working branch based on a branch name, 972 local working branch based on a branch name,
940 your local environment matches the "tip" of that development branch 973 your local environment matches the "tip" of that development branch
941 at the time you created your local branch, which could be 974 at the time you created your local branch, which could be
942 different from the files at the time of a similarly named release. 975 different from the files at the time of a similarly named release.
943 In other words, creating and checking out a local branch based on the 976 In other words, creating and checking out a local branch based on
944 <filename>&DISTRO_NAME;</filename> branch name is not the same as 977 the "&DISTRO_NAME;" branch name is not the same as
945 cloning and checking out the <filename>master</filename> branch. 978 cloning and checking out the "master" branch.
946 Keep reading to see how you create a local snapshot of a Yocto Project Release. 979 Keep reading to see how you create a local snapshot of a Yocto
980 Project Release.
947 </para> 981 </para>
948 982
949 <para> 983 <para>
950 Git uses "tags" to mark specific changes in a repository. 984 Git uses "tags" to mark specific changes in a repository.
951 Typically, a tag is used to mark a special point such as the final change 985 Typically, a tag is used to mark a special point such as the final
952 before a project is released. 986 change before a project is released.
953 You can see the tags used with the <filename>poky</filename> Git repository 987 You can see the tags used with the <filename>poky</filename> Git
954 by going to <ulink url='&YOCTO_GIT_URL;/cgit.cgi/poky/'></ulink> and 988 repository by going to
989 <ulink url='&YOCTO_GIT_URL;/cgit.cgi/poky/'></ulink> and
955 clicking on the 990 clicking on the
956 <filename><ulink url='&YOCTO_GIT_URL;/cgit.cgi/poky/refs/tags'>[...]</ulink></filename> 991 <filename><ulink url='&YOCTO_GIT_URL;/cgit.cgi/poky/refs/tags'>[...]</ulink></filename>
957 link beneath the "Tag" heading. 992 link beneath the "Tag" heading.
958 </para> 993 </para>
959 994
960 <para> 995 <para>
961 Some key tags are <filename>bernard-5.0</filename>, <filename>denzil-7.0</filename>, 996 Some key tags are <filename>dylan-9.0.0</filename>,
997 <filename>dora-10.0.0</filename>,
962 and <filename>&DISTRO_NAME;-&POKYVERSION;</filename>. 998 and <filename>&DISTRO_NAME;-&POKYVERSION;</filename>.
963 These tags represent Yocto Project releases. 999 These tags represent Yocto Project releases.
964 </para> 1000 </para>
@@ -1007,7 +1043,7 @@
1007 </para> 1043 </para>
1008 1044
1009 <para> 1045 <para>
1010 If you dont know much about Git, you should educate 1046 If you do not know much about Git, you should educate
1011 yourself by visiting the links previously mentioned. 1047 yourself by visiting the links previously mentioned.
1012 </para> 1048 </para>
1013 1049
@@ -1019,9 +1055,12 @@
1019 <itemizedlist> 1055 <itemizedlist>
1020 <listitem><para><emphasis><filename>git init</filename>:</emphasis> Initializes an empty Git repository. 1056 <listitem><para><emphasis><filename>git init</filename>:</emphasis> Initializes an empty Git repository.
1021 You cannot use Git commands unless you have a <filename>.git</filename> repository.</para></listitem> 1057 You cannot use Git commands unless you have a <filename>.git</filename> repository.</para></listitem>
1022 <listitem><para><emphasis><filename>git clone</filename>:</emphasis> Creates a clone of a repository. 1058 <listitem><para><emphasis><filename>git clone</filename>:</emphasis>
1023 During collaboration, this command allows you to create a local repository that is on 1059 Creates a local clone of a Git repository.
1024 equal footing with a fellow developer’s repository.</para></listitem> 1060 During collaboration, this command allows you to create a
1061 local Git repository that is on equal footing with a fellow
1062 developer’s Git repository.
1063 </para></listitem>
1025 <listitem><para><emphasis><filename>git add</filename>:</emphasis> Stages updated file contents 1064 <listitem><para><emphasis><filename>git add</filename>:</emphasis> Stages updated file contents
1026 to the index that 1065 to the index that
1027 Git uses to track changes. 1066 Git uses to track changes.
@@ -1111,11 +1150,18 @@
1111 </para> 1150 </para>
1112 1151
1113 <para> 1152 <para>
1114 The project also has contribution repositories known as "contrib" areas. 1153 The project also has an upstream contribution Git repository named
1115 These areas temporarily hold changes to the project that have been submitted or committed 1154 <filename>poky-contrib</filename>.
1116 by the Yocto Project development team and by community members that contribute to the project. 1155 You can see all the branches in this repository using the web interface
1117 The maintainer determines if the changes are qualified to be moved from the "contrib" areas 1156 of the
1118 into the "master" branch of the Git repository. 1157 <ulink url='&YOCTO_GIT_URL;'>Source Repositories</ulink> organized
1158 within the "Poky Support" area.
1159 These branches temporarily hold changes to the project that have been
1160 submitted or committed by the Yocto Project development team and by
1161 community members who contribute to the project.
1162 The maintainer determines if the changes are qualified to be moved
1163 from the "contrib" branches into the "master" branch of the Git
1164 repository.
1119 </para> 1165 </para>
1120 1166
1121 <para> 1167 <para>
@@ -1143,11 +1189,13 @@
1143 </para> 1189 </para>
1144 1190
1145 <para> 1191 <para>
1146 To summarize the environment: we have a single point of entry for changes into the project’s 1192 To summarize the environment: a single point of entry exists for
1147 "master" branch of the Git repository, which is controlled by the project’s maintainer. 1193 changes into the project’s "master" branch of the Git repository,
1148 And, we have a set of developers who independently develop, test, and submit changes 1194 which is controlled by the project’s maintainer.
1149 to "contrib" areas for the maintainer to examine. 1195 And, a set of developers exist who independently develop, test, and
1150 The maintainer then chooses which changes are going to become a permanent part of the project. 1196 submit changes to "contrib" areas for the maintainer to examine.
1197 The maintainer then chooses which changes are going to become a
1198 permanent part of the project.
1151 </para> 1199 </para>
1152 1200
1153 <para> 1201 <para>
@@ -1430,19 +1478,20 @@
1430 you used. It may also be helpful if you mention how you tested the change. 1478 you used. It may also be helpful if you mention how you tested the change.
1431 Provide as much detail as you can in the body of the commit message. 1479 Provide as much detail as you can in the body of the commit message.
1432 </para></listitem> 1480 </para></listitem>
1433 <listitem><para>If the change addresses a specific bug or issue that is 1481 <listitem><para>
1434 associated with a bug-tracking ID, include a reference to that ID in 1482 If the change addresses a specific bug or issue that is
1435 your detailed description. 1483 associated with a bug-tracking ID, include a reference to that
1436 For example, the Yocto Project uses a specific convention for bug 1484 ID in your detailed description.
1437 references - any commit that addresses a specific bug should include the 1485 For example, the Yocto Project uses a specific convention for
1438 bug ID in the description (typically at the beginning) as follows: 1486 bug references - any commit that addresses a specific bug should
1487 use the following form for the detailed description:
1439 <literallayout class='monospaced'> 1488 <literallayout class='monospaced'>
1440 [YOCTO #&lt;bug-id&gt;] 1489 Fixes [YOCTO #&lt;bug-id&gt;]
1441 1490
1442 &lt;detailed description of change&gt; 1491 &lt;detailed description of change&gt;
1443 </literallayout></para></listitem> 1492 </literallayout></para></listitem>
1444 Where &lt;bug-id&gt; is replaced with the specific bug ID from the 1493 Where &lt;bug-id&gt; is replaced with the specific bug ID from
1445 Yocto Project Bugzilla instance. 1494 the Yocto Project Bugzilla instance.
1446 </itemizedlist> 1495 </itemizedlist>
1447 </para> 1496 </para>
1448 1497
@@ -1466,10 +1515,16 @@
1466 <listitem><para>Make your changes in your local Git repository.</para></listitem> 1515 <listitem><para>Make your changes in your local Git repository.</para></listitem>
1467 <listitem><para>Stage your changes by using the <filename>git add</filename> 1516 <listitem><para>Stage your changes by using the <filename>git add</filename>
1468 command on each file you changed.</para></listitem> 1517 command on each file you changed.</para></listitem>
1469 <listitem><para>Commit the change by using the <filename>git commit</filename> 1518 <listitem><para>
1470 command and push it to the "contrib" repository. 1519 Commit the change by using the
1471 Be sure to provide a commit message that follows the project’s commit message standards 1520 <filename>git commit</filename> command.
1472 as described earlier.</para></listitem> 1521 Be sure to provide a commit message that follows the
1522 project’s commit message standards as described earlier.
1523 </para></listitem>
1524 <listitem><para>
1525 Push the change to the upstream "contrib" repository by
1526 using the <filename>git push</filename> command.
1527 </para></listitem>
1473 <listitem><para>Notify the maintainer that you have pushed a change by making a pull 1528 <listitem><para>Notify the maintainer that you have pushed a change by making a pull
1474 request. 1529 request.
1475 The Yocto Project provides two scripts that conveniently let you generate and send 1530 The Yocto Project provides two scripts that conveniently let you generate and send