summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
-rw-r--r--documentation/dev-manual/dev-manual-newbie.xml98
1 files changed, 61 insertions, 37 deletions
diff --git a/documentation/dev-manual/dev-manual-newbie.xml b/documentation/dev-manual/dev-manual-newbie.xml
index 81e425c491..bc95a20c2a 100644
--- a/documentation/dev-manual/dev-manual-newbie.xml
+++ b/documentation/dev-manual/dev-manual-newbie.xml
@@ -1,5 +1,6 @@
1<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" 1<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
2"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> 2"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
3[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >
3 4
4<chapter id='dev-manual-newbie'> 5<chapter id='dev-manual-newbie'>
5 6
@@ -7,11 +8,11 @@
7 8
8<para> 9<para>
9 This chapter helps you understand the Yocto Project as an open source development project. 10 This chapter helps you understand the Yocto Project as an open source development project.
10 In general, working in an open source environment is very different as compared to working in a 11 In general, working in an open source environment is very different from working in a
11 proprietary environment. 12 closed, proprietary environment.
12 Additionally, the Yocto Project uses specific tools and constructs as part of its development 13 Additionally, the Yocto Project uses specific tools and constructs as part of its development
13 environment. 14 environment.
14 The chapter specifically addresses open source philosophy, licensing issues, code repositories, 15 This chapter specifically addresses open source philosophy, licensing issues, code repositories,
15 the open source distributed version control system Git, and best practices using the Yocto Project. 16 the open source distributed version control system Git, and best practices using the Yocto Project.
16</para> 17</para>
17 18
@@ -20,10 +21,10 @@
20 21
21 <para> 22 <para>
22 Open source philosophy is characterized by software development directed by peer production 23 Open source philosophy is characterized by software development directed by peer production
23 and collaboration through a concerned community of developers. 24 and collaboration through an active community of developers.
24 Contrast this to the more standard centralized development models used by commercial software 25 Contrast this to the more standard centralized development models used by commercial software
25 companies where a finite set of developers produce a product for sale using a defined set 26 companies where a finite set of developers produce a product for sale using a defined set
26 of procedures that ultimately result in an end-product whose architecture and source material 27 of procedures that ultimately result in an end product whose architecture and source material
27 are closed to the public. 28 are closed to the public.
28 </para> 29 </para>
29 30
@@ -33,7 +34,7 @@
33 stake in the software project. 34 stake in the software project.
34 The open source environment contains new copyright, licensing, domain, and consumer issues 35 The open source environment contains new copyright, licensing, domain, and consumer issues
35 that differ from the more traditional development environment. 36 that differ from the more traditional development environment.
36 In an open source environment, the end-product, source material, and documentation are 37 In an open source environment, the end product, source material, and documentation are
37 all available to the public at no cost. 38 all available to the public at no cost.
38 </para> 39 </para>
39 40
@@ -58,7 +59,7 @@
58 59
59 <para> 60 <para>
60 The Yocto Project team maintains complete source repositories for all Yocto Project files 61 The Yocto Project team maintains complete source repositories for all Yocto Project files
61 <ulink url='http://git.yoctoproject.org/cgit/cgit.cgi'>here</ulink>. 62 at <ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi'></ulink>.
62 This web-based source code browser is organized into categories by function such as 63 This web-based source code browser is organized into categories by function such as
63 IDE Plugins, Matchbox, Poky, Yocto Linux Kernel, and so forth. 64 IDE Plugins, Matchbox, Poky, Yocto Linux Kernel, and so forth.
64 From the interface, you can click on any particular item in the "Name" column and 65 From the interface, you can click on any particular item in the "Name" column and
@@ -73,13 +74,13 @@
73 Conversely, if you are a developer that is not interested in contributing back to the 74 Conversely, if you are a developer that is not interested in contributing back to the
74 Yocto Project, you have the ability to simply download and extract release tarballs 75 Yocto Project, you have the ability to simply download and extract release tarballs
75 and use them within the Yocto Project environment. 76 and use them within the Yocto Project environment.
76 All that is required is a particular release of Yocto Project, a kernel, and 77 All that is required is a particular release of the Yocto Project and
77 your application source code. 78 your application source code.
78 </para> 79 </para>
79 80
80 <para> 81 <para>
81 For any supported release of Yocto Project, you can go to the Yocto Project website’s 82 For any supported release of Yocto Project, you can go to the Yocto Project website’s
82 <ulink url='http://www.yoctoproject.org/download'>download page</ulink> and get a 83 <ulink url='&YOCTO_HOME_URL;/download'>download page</ulink> and get a
83 tarball of the release. 84 tarball of the release.
84 You can also go to this site to download any supported BSP tarballs. 85 You can also go to this site to download any supported BSP tarballs.
85 Unpacking the tarball gives you a hierarchical directory structure of Yocto Project 86 Unpacking the tarball gives you a hierarchical directory structure of Yocto Project
@@ -94,15 +95,15 @@
94 <para> 95 <para>
95 In summary, here is where you can get the Yocto Project files needed for development: 96 In summary, here is where you can get the Yocto Project files needed for development:
96 <itemizedlist> 97 <itemizedlist>
97 <listitem><para><emphasis><ulink url='http://git.yoctoproject.org/cgit/cgit.cgi'>Source Repositories:</ulink></emphasis> 98 <listitem><para><emphasis><ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi'>Source Repositories:</ulink></emphasis>
98 This area contains IDE Plugins, Matchbox, Poky, Poky Support, Tools, Yocto Linux Kernel, and Yocto 99 This area contains IDE Plugins, Matchbox, Poky, Poky Support, Tools, Yocto Linux Kernel, and Yocto
99 Metadata Layers. 100 Metadata Layers.
100 You can create Git repositories for each of these areas.</para> 101 You can create Git repositories for each of these areas.</para>
101 <para> 102 <para>
102 <imagedata fileref="figures/source-repos.png" align="center" width="6in" depth="4in" /> 103 <imagedata fileref="figures/source-repos.png" align="center" width="6in" depth="4in" />
103 </para></listitem> 104 </para></listitem>
104 <listitem><para><anchor id='index-downloads' /><emphasis><ulink url='http://downloads.yoctoproject.org/releases/'>Index of /releases:</ulink></emphasis> 105 <listitem><para><anchor id='index-downloads' /><emphasis><ulink url='&YOCTO_DL_URL;/releases/'>Index of /releases:</ulink></emphasis>
105 This area contains an index releases such as 106 This area contains index releases such as
106 the <trademark class='trade'>Eclipse</trademark> 107 the <trademark class='trade'>Eclipse</trademark>
107 Yocto Plug-in, miscellaneous support, Poky, pseudo, cross-development toolchains, 108 Yocto Plug-in, miscellaneous support, Poky, pseudo, cross-development toolchains,
108 and all released versions of Yocto Project in the form of images or tarballs. 109 and all released versions of Yocto Project in the form of images or tarballs.
@@ -111,11 +112,11 @@
111 <para> 112 <para>
112 <imagedata fileref="figures/index-downloads.png" align="center" width="6in" depth="4in" /> 113 <imagedata fileref="figures/index-downloads.png" align="center" width="6in" depth="4in" />
113 </para></listitem> 114 </para></listitem>
114 <listitem><para><emphasis><ulink url='http://www.yoctoproject.org/download'>Yocto Project Download Page</ulink></emphasis> 115 <listitem><para><emphasis><ulink url='&YOCTO_HOME_URL;/download'>Yocto Project Download Page</ulink></emphasis>
115 This page on the Yocto Project website allows you to download any Yocto Project 116 This page on the Yocto Project website allows you to download any Yocto Project
116 release or Board Support Package (BSP) in tarball form. 117 release or Board Support Package (BSP) in tarball form.
117 The tarballs are similar to those found in the 118 The tarballs are similar to those found in the
118 <ulink url='http://downloads.yoctoproject.org/releases/'>Index of /releases:</ulink> area.</para> 119 <ulink url='&YOCTO_DL_URL;/releases/'>Index of /releases:</ulink> area.</para>
119 <para> 120 <para>
120 <imagedata fileref="figures/yp-download.png" align="center" width="6in" depth="4in" /> 121 <imagedata fileref="figures/yp-download.png" align="center" width="6in" depth="4in" />
121 </para></listitem> 122 </para></listitem>
@@ -305,7 +306,7 @@
305 306
306 <para> 307 <para>
307 You can find a list of the combined SPDX and OSI licenses that the Yocto Project uses 308 You can find a list of the combined SPDX and OSI licenses that the Yocto Project uses
308 <ulink url='http://git.yoctoproject.org/cgit/cgit.cgi/poky/tree/meta/files/common-licenses'>here</ulink>. 309 <ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi/poky/tree/meta/files/common-licenses'>here</ulink>.
309 This wiki page discusses the license infrastructure used by the Yocto Project. 310 This wiki page discusses the license infrastructure used by the Yocto Project.
310 </para> 311 </para>
311</section> 312</section>
@@ -316,7 +317,10 @@
316 <para> 317 <para>
317 The Yocto Project uses Git, which is a free, open source distributed version control system. 318 The Yocto Project uses Git, which is a free, open source distributed version control system.
318 Git supports distributed development, non-linear development, and can handle large projects. 319 Git supports distributed development, non-linear development, and can handle large projects.
319 It is best that you know how to work with Git if you are going to use Yocto Project for development. 320 It is best that you have some fundamental understanding of how Git tracks projects and
321 how to work with Git if you are going to use Yocto Project for development.
322 This section provides a quick overview of how Git works and provides you with a summary
323 of some essential Git commands.
320 </para> 324 </para>
321 325
322 <para> 326 <para>
@@ -423,7 +427,7 @@
423 In particular, the information covers basic practices that describe roles and actions in a 427 In particular, the information covers basic practices that describe roles and actions in a
424 collaborative development environment. 428 collaborative development environment.
425 Again, if you are familiar with this type of development environment, you might want to just 429 Again, if you are familiar with this type of development environment, you might want to just
426 skip the section. 430 skip this section.
427 </para> 431 </para>
428 432
429 <para> 433 <para>
@@ -436,7 +440,7 @@
436 The maintainer is responsible for allowing changes in from other developers and for 440 The maintainer is responsible for allowing changes in from other developers and for
437 organizing the underlying branch structure to reflect release strategies and so forth. 441 organizing the underlying branch structure to reflect release strategies and so forth.
438 <note>You can see who is the maintainer for Yocto Project files by examining the 442 <note>You can see who is the maintainer for Yocto Project files by examining the
439 <filename>distro_tracking_fields</filename> file in the Yocto Project 443 <filename>distro_tracking_fields.inc</filename> file in the Yocto Project
440 <filename>meta/conf/distro/include</filename> directory.</note> 444 <filename>meta/conf/distro/include</filename> directory.</note>
441 </para> 445 </para>
442 446
@@ -475,7 +479,7 @@
475 "master" branch of the Git repository, which is controlled by the project’s maintainer. 479 "master" branch of the Git repository, which is controlled by the project’s maintainer.
476 And, we have a set of developers who independently develop, test, and submit changes 480 And, we have a set of developers who independently develop, test, and submit changes
477 to "contrib" areas for the maintainer to examine. 481 to "contrib" areas for the maintainer to examine.
478 The maintainer then chooses which changes are going to become permanently a part of the project. 482 The maintainer then chooses which changes are going to become a permanent part of the project.
479 </para> 483 </para>
480 484
481 <para> 485 <para>
@@ -489,12 +493,15 @@
489 For more information about Git workflows, see the workflow topics in the 493 For more information about Git workflows, see the workflow topics in the
490 <ulink url='http://book.git-scm.com'>Git Community Book</ulink>. 494 <ulink url='http://book.git-scm.com'>Git Community Book</ulink>.
491 <itemizedlist> 495 <itemizedlist>
492 <listitem><para><emphasis>Make Small Changes:</emphasis> It is best to keep your changes you commit 496 <listitem><para><emphasis>Make Small Changes:</emphasis> It is best to keep the changes you commit
493 small as compared to bundling many disparate changes into a single commit. 497 small as compared to bundling many disparate changes into a single commit.
494 This practice not only keeps things manageable but also allows the maintainer 498 This practice not only keeps things manageable but also allows the maintainer
495 to more easily include or refuse changes.</para> 499 to more easily include or refuse changes.</para>
496 <para>It is also good practice to leave the repository in a state that allows you to 500 <para>It is also good practice to leave the repository in a state that allows you to
497 still successfully build your project.</para></listitem> 501 still successfully build your project. In other words, do not commit half of a feature,
502 then add the other half in a separate, later commit.
503 Each commit should take you from one buildable project state to another
504 buildable state.</para></listitem>
498 <listitem><para><emphasis>Use Branches Liberally:</emphasis> It is very easy to create, use, and 505 <listitem><para><emphasis>Use Branches Liberally:</emphasis> It is very easy to create, use, and
499 delete local branches in your working Git repository. 506 delete local branches in your working Git repository.
500 You can name these branches anything you like. 507 You can name these branches anything you like.
@@ -527,7 +534,7 @@
527 <filename>send-pull-request</filename> that ship with the release to facilitate this 534 <filename>send-pull-request</filename> that ship with the release to facilitate this
528 workflow. 535 workflow.
529 You can find these scripts in the local Yocto Project files Git repository in 536 You can find these scripts in the local Yocto Project files Git repository in
530 <filename>scripts</filename>.</para></listitem> 537 the <filename>scripts</filename> directory.</para></listitem>
531 <listitem><para><emphasis>Patch Workflow:</emphasis> This workflow allows you to notify the 538 <listitem><para><emphasis>Patch Workflow:</emphasis> This workflow allows you to notify the
532 maintainer through an email that you have a change (or patch) you would like considered 539 maintainer through an email that you have a change (or patch) you would like considered
533 for the "master" branch of the Git repository. 540 for the "master" branch of the Git repository.
@@ -548,7 +555,7 @@
548 changes, can be used to communicate changes and problems with developers, can be used to 555 changes, can be used to communicate changes and problems with developers, can be used to
549 submit and review patches, and can be used to manage quality assurance. 556 submit and review patches, and can be used to manage quality assurance.
550 The home page for the Yocto Project implementation of Bugzilla is 557 The home page for the Yocto Project implementation of Bugzilla is
551 <ulink url='http://bugzilla.yoctoproject.org'>http://bugzilla.yoctoproject.org</ulink>. 558 <ulink url='&YOCTO_BUGZILLA_URL;'>&YOCTO_BUGZILLA_URL;</ulink>.
552 </para> 559 </para>
553 560
554 <para> 561 <para>
@@ -559,7 +566,7 @@
559 Bugzilla. 566 Bugzilla.
560 You can find more information on defect management, bug tracking, and feature request 567 You can find more information on defect management, bug tracking, and feature request
561 processes all accomplished through the Yocto Project Bugzilla on the wiki page 568 processes all accomplished through the Yocto Project Bugzilla on the wiki page
562 <ulink url='https://wiki.yoctoproject.org/wiki/Bugzilla_Configuration_and_Bug_Tracking'>here</ulink>. 569 <ulink url='&YOCTO_WIKI_URL;/wiki/Bugzilla_Configuration_and_Bug_Tracking'>here</ulink>.
563 <orderedlist> 570 <orderedlist>
564 <listitem><para>Always use the Yocto Project implementation of Bugzilla to submit 571 <listitem><para>Always use the Yocto Project implementation of Bugzilla to submit
565 a bug.</para></listitem> 572 a bug.</para></listitem>
@@ -602,27 +609,28 @@
602 609
603 <para> 610 <para>
604 Contributions to the Yocto Project are very welcome. 611 Contributions to the Yocto Project are very welcome.
612 Because the Yocto Project is extremely configurable and flexible, we recognize that developers
613 will want to extend, configure or optimize it for their specific uses.
605 You should send patches to the appropriate Yocto Project mailing list to get them 614 You should send patches to the appropriate Yocto Project mailing list to get them
606 in front of the Yocto Project Maintainer. 615 in front of the Yocto Project Maintainer.
607 For a list of the Yocto Project mailing lists, see the 616 For a list of the Yocto Project mailing lists, see the
608 "<ulink url='http://www.yoctoproject.org/docs/1.1.1/poky-ref-manual/poky-ref-manual.html#resources-mailinglist'>Mailing lists</ulink>" section in 617 "<ulink url='&YOCTO_DOCS_REF_URL;#resources-mailinglist'>Mailing lists</ulink>" section in
609 <ulink url='http://www.yoctoproject.org/docs/1.1.1/poky-ref-manual/poky-ref-manual.html'> The 618 The Yocto Project Reference Manual.
610 Yocto Project Reference Manual</ulink>.
611 </para> 619 </para>
612 620
613 <para> 621 <para>
614 Following is some guidance on which mailing list to use for what type of defect: 622 The following is some guidance on which mailing list to use for what type of defect:
615 <itemizedlist> 623 <itemizedlist>
616 <listitem><para>For defects against the Yocto Project build system Poky, send 624 <listitem><para>For defects against the Yocto Project build system Poky, send
617 your patch to the 625 your patch to the
618 <ulink url='http://lists.yoctoproject.org/listinfo/poky'></ulink> mailing list. 626 <ulink url='&YOCTO_LISTS_URL;/listinfo/poky'></ulink> mailing list.
619 This mailing list corresponds to issues that are not specific to the Yocto Project but 627 This mailing list corresponds to issues that are not specific to the Yocto Project but
620 are part of the OE-core. 628 are part of the OE-core.
621 For example, a defect against anything in the <filename>meta</filename> layer 629 For example, a defect against anything in the <filename>meta</filename> layer
622 or the BitBake Manual could be sent to this mailing list.</para></listitem> 630 or the BitBake Manual could be sent to this mailing list.</para></listitem>
623 <listitem><para>For defects against Yocto-specific layers, tools, and Yocto Project 631 <listitem><para>For defects against Yocto-specific layers, tools, and Yocto Project
624 documentation use the 632 documentation use the
625 <ulink url='http://lists.yoctoproject.org/listinfo/yocto'></ulink> mailing list. 633 <ulink url='&YOCTO_LISTS_URL;/listinfo/yocto'></ulink> mailing list.
626 This mailing list corresponds to Yocto-specific areas such as 634 This mailing list corresponds to Yocto-specific areas such as
627 <filename>meta-yocto</filename>, <filename>meta-intel</filename>, 635 <filename>meta-yocto</filename>, <filename>meta-intel</filename>,
628 <filename>linux-yocto</filename>, and <filename>documentation</filename>.</para></listitem> 636 <filename>linux-yocto</filename>, and <filename>documentation</filename>.</para></listitem>
@@ -630,7 +638,7 @@
630 </para> 638 </para>
631 639
632 <para> 640 <para>
633 When you send a patch, be sure to include a "signed-off-by:" 641 When you send a patch, be sure to include a "Signed-off-by:"
634 line in the same style as required by the Linux kernel. 642 line in the same style as required by the Linux kernel.
635 Adding this line signifies the developer has agreed to the Developer's Certificate of Origin 1.1 643 Adding this line signifies the developer has agreed to the Developer's Certificate of Origin 1.1
636 as follows: 644 as follows:
@@ -672,11 +680,14 @@
672 <para> 680 <para>
673 In a collaborative environment, it is necessary to have some sort of standard 681 In a collaborative environment, it is necessary to have some sort of standard
674 or method through which you submit changes. 682 or method through which you submit changes.
675 Otherwise, things could get quite chaotic. 683 Otherwise, things could get quite chaotic.
684 One general practice to follow is to make small, controlled changes to the
685 Yocto Project.
686 Keeping changes small and isolated lets you best keep pace with future Yocto Project changes.
676 </para> 687 </para>
677 688
678 <para> 689 <para>
679 When you form a commit, you must follow certain standards established by the 690 When you create a commit, you must follow certain standards established by the
680 Yocto Project development team. 691 Yocto Project development team.
681 For each commit, you must provide a single-line summary of the change and you 692 For each commit, you must provide a single-line summary of the change and you
682 almost always provide a more detailed description of what you did (i.e. the body 693 almost always provide a more detailed description of what you did (i.e. the body
@@ -710,7 +721,7 @@
710 <para> 721 <para>
711 You can find more guidance on creating well-formed commit messages at this OpenEmbedded 722 You can find more guidance on creating well-formed commit messages at this OpenEmbedded
712 wiki page: 723 wiki page:
713 <ulink url='http://www.openembedded.org/wiki/Commit_Patch_Message_Guidelines'></ulink>. 724 <ulink url='&OE_HOME_URL;/wiki/Commit_Patch_Message_Guidelines'></ulink>.
714 </para> 725 </para>
715 726
716 <para> 727 <para>
@@ -774,7 +785,7 @@
774 See the earlier section 785 See the earlier section
775 "<link linkend='how-to-submit-a-change'>How to Submit a Change</link>" 786 "<link linkend='how-to-submit-a-change'>How to Submit a Change</link>"
776 for Yocto Project commit message standards.</para></listitem> 787 for Yocto Project commit message standards.</para></listitem>
777 <listitem><para>Format the commit into an email messsage. 788 <listitem><para>Format the commit into an email message.
778 To format commits, use the <filename>git format-patch</filename> command. 789 To format commits, use the <filename>git format-patch</filename> command.
779 When you provide the command, you must include a revision list or a number of patches 790 When you provide the command, you must include a revision list or a number of patches
780 as part of the command. 791 as part of the command.
@@ -789,6 +800,11 @@
789 <para>If you provide several commits as part of the command, 800 <para>If you provide several commits as part of the command,
790 the <filename>git format-patch</filename> command produces a numbered 801 the <filename>git format-patch</filename> command produces a numbered
791 series of files in the current directory – one for each commit. 802 series of files in the current directory – one for each commit.
803 If you have more than one patch, you should also use the
804 <filename>--cover</filename> option with the command, which generates a
805 cover letter as the first "patch" in the series.
806 You can then edit the cover letter to provide a description for
807 the series of patches.
792 For information on the <filename>git format-patch</filename> command, 808 For information on the <filename>git format-patch</filename> command,
793 see <filename>GIT_FORMAT_PATCH(1)</filename> displayed using the 809 see <filename>GIT_FORMAT_PATCH(1)</filename> displayed using the
794 <filename>man git-format-patch</filename> command.</para></listitem> 810 <filename>man git-format-patch</filename> command.</para></listitem>
@@ -801,7 +817,15 @@
801 or remote Mail Transport Agent (MTA) such as 817 or remote Mail Transport Agent (MTA) such as
802 <filename>msmtp</filename>, <filename>sendmail</filename>, or through a direct 818 <filename>msmtp</filename>, <filename>sendmail</filename>, or through a direct
803 <filename>smtp</filename> configuration in your Git <filename>config</filename> 819 <filename>smtp</filename> configuration in your Git <filename>config</filename>
804 file.</para> 820 file.
821 If you are submitting patches through email only, it is very important
822 that you submit them without any whitespace or HTML formatting that
823 either you or your mailer introduces.
824 The maintainer that receives your patches needs to be able to save and
825 apply them directly from your emails.
826 A good way to verify that what you are sending will be applicable by the
827 maintainer is to do a dry run and send them to yourself and then
828 save and apply them as the maintainer would.</para>
805 <para>The <filename>git send-email</filename> command is the preferred method 829 <para>The <filename>git send-email</filename> command is the preferred method
806 for sending your patches since there is no risk of compromising whitespace 830 for sending your patches since there is no risk of compromising whitespace
807 in the body of the message, which can occur when you use your own mail client. 831 in the body of the message, which can occur when you use your own mail client.