| <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" |
| "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" |
| [<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] > |
| |
| <chapter id='dev-manual-newbie'> |
| |
| <title>The Yocto Project Open Source Development Environment</title> |
| |
| <section id="usingpoky-changes-collaborate"> |
| <title>Setting Up a Team Yocto Project Development Environment</title> |
| |
| <para> |
| It might not be immediately clear how you can use the Yocto |
| Project in a team development environment, or scale it for a large |
| team of developers. |
| One of the strengths of the Yocto Project is that it is extremely |
| flexible. |
| Thus, you can adapt it to many different use cases and scenarios. |
| However, these characteristics can cause a struggle if you are trying |
| to create a working setup that scales across a large team. |
| </para> |
| |
| <para> |
| To help you understand how to set up this type of environment, |
| this section presents a procedure that gives you the information |
| to learn how to get the results you want. |
| The procedure is high-level and presents some of the project's most |
| successful experiences, practices, solutions, and available |
| technologies that work well. |
| Keep in mind, the procedure here is a starting point. |
| You can build off it and customize it to fit any |
| particular working environment and set of practices. |
| <orderedlist> |
| <listitem><para> |
| <emphasis>Determine Who is Going to be Developing:</emphasis> |
| You need to understand who is going to be doing anything |
| related to the Yocto Project and what their roles would be. |
| Making this determination is essential to completing the |
| steps two and three, which are to get your equipment together |
| and set up your development environment's hardware topology. |
| </para> |
| |
| <para>The following roles exist: |
| <itemizedlist> |
| <listitem><para> |
| <emphasis>Application Development:</emphasis> |
| These types of developers do application level work |
| on top of an existing software stack. |
| </para></listitem> |
| <listitem><para> |
| <emphasis>Core System Development:</emphasis> |
| These types of developers work on the contents of the |
| operating system image itself. |
| </para></listitem> |
| <listitem><para> |
| <emphasis>Build Engineer:</emphasis> |
| This type of developer manages Autobuilders and |
| releases. |
| Not all environments need a Build Engineer. |
| </para></listitem> |
| <listitem><para> |
| <emphasis>Test Engineer:</emphasis> |
| This type of developer creates and manages automated |
| tests needed to ensure all application and core |
| system development meets desired quality standards. |
| </para></listitem> |
| </itemizedlist> |
| </para></listitem> |
| <listitem><para> |
| <emphasis>Gather the Hardware:</emphasis> |
| Based on the size and make-up of the team, get the hardware |
| together. |
| Any development, build, or test engineer should be using |
| a system that is running a supported Linux distribution. |
| Systems, in general, should be high performance (e.g. dual, |
| six-core Xeons with 24 Gbytes of RAM and plenty of disk space). |
| You can help ensure efficiency by having any machines used |
| for testing or that run Autobuilders be as high performance |
| as possible. |
| </para></listitem> |
| <listitem><para> |
| <emphasis>Understand the Hardware Topology of the Environment:</emphasis> |
| Now that you know how many developers and support engineers |
| are required, you can understand the topology of the |
| hardware environment. |
| The following figure shows a moderately sized Yocto Project |
| development environment. |
| |
| <para role="writernotes"> |
| Need figure.</para> |
| |
| </para></listitem> |
| <listitem><para> |
| <emphasis>Use Git as Your Source Control Manager (SCM):</emphasis> |
| Keeping your |
| <ulink url='&YOCTO_DOCS_REF_URL;#metadata'>Metadata</ulink> |
| and any software you are developing under the |
| control of an SCM system that is compatible |
| with the OpenEmbedded build system is advisable. |
| Of the SCMs BitBake supports, the |
| Yocto Project team strongly recommends using |
| <ulink url='&YOCTO_DOCS_REF_URL;#git'>Git</ulink>. |
| Git is a distributed system that is easy to backup, |
| allows you to work remotely, and then connects back to the |
| infrastructure. |
| <note> |
| For information about BitBake, see the |
| <ulink url='&YOCTO_DOCS_BB_URL;'>BitBake User Manual</ulink>. |
| </note></para> |
| |
| <para>It is relatively easy to set up Git services and create |
| infrastructure like |
| <ulink url='&YOCTO_GIT_URL;'>http://git.yoctoproject.org</ulink>, |
| which is based on server software called |
| <filename>gitolite</filename> with <filename>cgit</filename> |
| being used to generate the web interface that lets you view the |
| repositories. |
| The <filename>gitolite</filename> software identifies users |
| using SSH keys and allows branch-based |
| access controls to repositories that you can control as little |
| or as much as necessary. |
| |
| <note> |
| The setup of these services is beyond the scope of this |
| manual. |
| However, sites such as these exist that describe how to |
| perform setup: |
| <itemizedlist> |
| <listitem><para> |
| <ulink url='http://git-scm.com/book/ch4-8.html'>Git documentation</ulink>: |
| Describes how to install <filename>gitolite</filename> |
| on the server. |
| </para></listitem> |
| <listitem><para> |
| <ulink url='http://sitaramc.github.com/gitolite/master-toc.html'>The <filename>gitolite</filename> master index</ulink>: |
| All topics for <filename>gitolite</filename>. |
| </para></listitem> |
| <listitem><para> |
| <ulink url='https://git.wiki.kernel.org/index.php/Interfaces,_frontends,_and_tools'>Interfaces, frontends, and tools</ulink>: |
| Documentation on how to create interfaces and frontends |
| for Git. |
| </para></listitem> |
| </itemizedlist> |
| </note> |
| </para></listitem> |
| <listitem><para> |
| <emphasis>Set up the Application Development Machines:</emphasis> |
| As mentioned earlier, application developers are creating |
| applications on top of existing software stacks. |
| Following are some best practices for setting up machines |
| that do application development: |
| <itemizedlist> |
| <listitem><para> |
| Use a pre-built toolchain that |
| contains the software stack itself. |
| Then, develop the application code on top of the |
| stack. |
| This method works well for small numbers of relatively |
| isolated applications. |
| </para></listitem> |
| <listitem><para> |
| When possible, use the Yocto Project |
| plug-in for the |
| <trademark class='trade'>Eclipse</trademark> IDE |
| and SDK development practices. |
| For more information, see the |
| "<ulink url='&YOCTO_DOCS_SDK_URL;'>Yocto Project Application Development and the Extensible Software Development Kit (eSDK)</ulink>" |
| manual. |
| </para></listitem> |
| <listitem><para> |
| Keep your cross-development toolchains updated. |
| You can do this through provisioning either as new |
| toolchain downloads or as updates through a package |
| update mechanism using <filename>opkg</filename> |
| to provide updates to an existing toolchain. |
| The exact mechanics of how and when to do this are a |
| question for local policy. |
| </para></listitem> |
| <listitem><para> |
| Use multiple toolchains installed locally |
| into different locations to allow development across |
| versions. |
| </para></listitem> |
| </itemizedlist> |
| </para></listitem> |
| <listitem><para> |
| <emphasis>Set up the Core Development Machines:</emphasis> |
| As mentioned earlier, these types of developers work on the |
| contents of the operating system itself. |
| Following are some best practices for setting up machines |
| used for developing images: |
| <itemizedlist> |
| <listitem><para> |
| Have the Yocto Project build system itself available on |
| the developer workstations so developers can run their own |
| builds and directly rebuild the software stack. |
| </para></listitem> |
| <listitem><para> |
| Keep the core system unchanged as much as |
| possible and do your work in layers on top of the |
| core system. |
| Doing so gives you a greater level of portability when |
| upgrading to new versions of the core system or Board |
| Support Packages (BSPs). |
| </para></listitem> |
| <listitem><para> |
| Share layers amongst the developers of a |
| particular project and contain the policy configuration |
| that defines the project. |
| </para></listitem> |
| </itemizedlist> |
| </para></listitem> |
| <listitem><para> |
| <emphasis>Set up an Autobuilder:</emphasis> |
| Autobuilders are often the core of the development |
| environment. |
| It is here that changes from individual developers are brought |
| together and centrally tested and subsequent decisions about |
| releases can be made. |
| Autobuilders also allow for "continuous integration" style |
| testing of software components and regression identification |
| and tracking.</para> |
| |
| <para>See "<ulink url='http://autobuilder.yoctoproject.org'>Yocto Project Autobuilder</ulink>" |
| for more information and links to buildbot. |
| The Yocto Project team has found this implementation |
| works well in this role. |
| A public example of this is the Yocto Project |
| Autobuilders, which we use to test the overall health of the |
| project.</para> |
| |
| <para>The features of this system are: |
| <itemizedlist> |
| <listitem><para> |
| Highlights when commits break the build. |
| </para></listitem> |
| <listitem><para> |
| Populates an sstate cache from which |
| developers can pull rather than requiring local |
| builds. |
| </para></listitem> |
| <listitem><para> |
| Allows commit hook triggers, |
| which trigger builds when commits are made. |
| </para></listitem> |
| <listitem><para> |
| Allows triggering of automated image booting |
| and testing under the QuickEMUlator (QEMU). |
| </para></listitem> |
| <listitem><para> |
| Supports incremental build testing and |
| from-scratch builds. |
| </para></listitem> |
| <listitem><para> |
| Shares output that allows developer |
| testing and historical regression investigation. |
| </para></listitem> |
| <listitem><para> |
| Creates output that can be used for releases. |
| </para></listitem> |
| <listitem><para> |
| Allows scheduling of builds so that resources |
| can be used efficiently. |
| </para></listitem> |
| </itemizedlist> |
| </para></listitem> |
| <listitem><para> |
| <emphasis>Set up Test Machines:</emphasis> |
| Use a small number of shared, high performance systems |
| for testing purposes. |
| Developers can use these systems for wider, more |
| extensive testing while they continue to develop |
| locally using their primary development system. |
| </para></listitem> |
| <listitem><para> |
| <emphasis>Document Policies and Change Flow:</emphasis> |
| The Yocto Project itself uses a hierarchical structure and a |
| pull model. |
| Scripts exist to create and send pull requests |
| (i.e. <filename>create-pull-request</filename> and |
| <filename>send-pull-request</filename>). |
| This model is in line with other open source projects where |
| maintainers are responsible for specific areas of the project |
| and a single maintainer handles the final "top-of-tree" merges. |
| <note> |
| You can also use a more collective push model. |
| The <filename>gitolite</filename> software supports both the |
| push and pull models quite easily. |
| </note></para> |
| |
| <para>As with any development environment, it is important |
| to document the policy used as well as any main project |
| guidelines so they are understood by everyone. |
| It is also a good idea to have well structured |
| commit messages, which are usually a part of a project's |
| guidelines. |
| Good commit messages are essential when looking back in time and |
| trying to understand why changes were made.</para> |
| |
| <para>If you discover that changes are needed to the core |
| layer of the project, it is worth sharing those with the |
| community as soon as possible. |
| Chances are if you have discovered the need for changes, |
| someone else in the community needs them also. |
| </para></listitem> |
| <listitem><para> |
| <emphasis>Development Environment Summary:</emphasis> |
| Aside from the previous steps, some best practices exist |
| within the Yocto Project development environment. |
| Consider the following: |
| <itemizedlist> |
| <listitem><para> |
| Use <ulink url='&YOCTO_DOCS_REF_URL;#git'>Git</ulink> |
| as the source control system. |
| </para></listitem> |
| <listitem><para> |
| Maintain your Metadata in layers that make sense |
| for your situation. |
| See the "<link linkend='understanding-and-creating-layers'>Understanding |
| and Creating Layers</link>" section for more information on |
| layers. |
| </para></listitem> |
| <listitem><para> |
| Separate the project's Metadata and code by using |
| separate Git repositories. |
| See the |
| "<ulink url='&YOCTO_DOCS_REF_URL;#yocto-project-repositories'>Yocto Project Source Repositories</ulink>" |
| section for information on these repositories. |
| See the |
| "<link linkend='working-with-yocto-project-source-files'>Working With Yocto Project Source Files</link>" |
| section for information on how to set up local Git |
| repositories for related upstream Yocto Project |
| Git repositories. |
| </para></listitem> |
| <listitem><para> |
| Set up the directory for the shared state cache |
| (<ulink url='&YOCTO_DOCS_REF_URL;#var-SSTATE_DIR'><filename>SSTATE_DIR</filename></ulink>) |
| where it makes sense. |
| For example, set up the sstate cache on a system used |
| by developers in the same organization and share the |
| same source directories on their machines. |
| </para></listitem> |
| <listitem><para> |
| Set up an Autobuilder and have it populate the |
| sstate cache and source directories. |
| </para></listitem> |
| <listitem><para> |
| The Yocto Project community encourages you |
| to send patches to the project to fix bugs or add features. |
| If you do submit patches, follow the project commit |
| guidelines for writing good commit messages. |
| See the "<link linkend='how-to-submit-a-change'>Submitting a Change to the Yocto Project</link>" |
| section. |
| </para></listitem> |
| <listitem><para> |
| Send changes to the core sooner than later |
| as others are likely to run into the same issues. |
| For some guidance on mailing lists to use, see the list in the |
| "<link linkend='how-to-submit-a-change'>Submitting a Change to the Yocto Project</link>" |
| section. |
| For a description of the available mailing lists, see the |
| "<ulink url='&YOCTO_DOCS_REF_URL;#resources-mailinglist'>Mailing Lists</ulink>" |
| section in the Yocto Project Reference Manual. |
| </para></listitem> |
| </itemizedlist> |
| </para></listitem> |
| </orderedlist> |
| </para> |
| </section> |
| |
| <section id='submitting-a-defect-against-the-yocto-project'> |
| <title>Submitting a Defect Against the Yocto Project</title> |
| |
| <para> |
| Use the Yocto Project implementation of |
| <ulink url='http://www.bugzilla.org/about/'>Bugzilla</ulink> |
| to submit a defect (bug) against the Yocto Project. |
| For additional information on this implementation of Bugzilla see the |
| "<ulink url='&YOCTO_DOCS_REF_URL;#resources-bugtracker'>Yocto Project Bugzilla</ulink>" |
| section in the Yocto Project Reference Manual. |
| For more detail on any of the following steps, see the Yocto Project |
| <ulink url='&YOCTO_WIKI_URL;/wiki/Bugzilla_Configuration_and_Bug_Tracking'>Bugzilla wiki page</ulink>. |
| </para> |
| |
| <para> |
| Use the following general steps to submit a bug" |
| |
| <orderedlist> |
| <listitem><para> |
| Open the Yocto Project implementation of |
| <ulink url='&YOCTO_BUGZILLA_URL;'>Bugzilla</ulink>. |
| </para></listitem> |
| <listitem><para> |
| Click "File a Bug" to enter a new bug. |
| </para></listitem> |
| <listitem><para> |
| Choose the appropriate "Classification", "Product", and |
| "Component" for which the bug was found. |
| Bugs for the Yocto Project fall into one of several |
| classifications, which in turn break down into several |
| products and components. |
| For example, for a bug against the |
| <filename>meta-intel</filename> layer, you would choose |
| "Build System, Metadata & Runtime", "BSPs", and |
| "bsps-meta-intel", respectively. |
| </para></listitem> |
| <listitem><para> |
| Choose the "Version" of the Yocto Project for which you found |
| the bug (e.g. &DISTRO;). |
| </para></listitem> |
| <listitem><para> |
| Determine and select the "Severity" of the bug. |
| The severity indicates how the bug impacted your work. |
| </para></listitem> |
| <listitem><para> |
| Choose the "Hardware" that the bug impacts. |
| </para></listitem> |
| <listitem><para> |
| Choose the "Architecture" that the bug impacts. |
| </para></listitem> |
| <listitem><para> |
| Choose a "Documentation change" item for the bug. |
| Fixing a bug might or might not affect the Yocto Project |
| documentation. |
| If you are unsure of the impact to the documentation, select |
| "Don't Know". |
| </para></listitem> |
| <listitem><para> |
| Provide a brief "Summary" of the bug. |
| Try to limit your summary to just a line or two and be sure |
| to capture the essence of the bug. |
| </para></listitem> |
| <listitem><para> |
| Provide a detailed "Description" of the bug. |
| You should provide as much detail as you can about the context, |
| behavior, output, and so forth that surrounds the bug. |
| You can even attach supporting files for output from logs by |
| using the "Add an attachment" button. |
| </para></listitem> |
| <listitem><para> |
| Click the "Submit Bug" button submit the bug. |
| A new Bugzilla number is assigned to the bug and the defect |
| is logged in the bug tracking system. |
| </para></listitem> |
| </orderedlist> |
| Once you file a bug, the bug is processed by the Yocto Project Bug |
| Triage Team and further details concerning the bug are assigned |
| (e.g. priority and owner). |
| You are the "Submitter" of the bug and any further categorization, |
| progress, or comments on the bug result in Bugzilla sending you an |
| automated email concerning the particular change or progress to the |
| bug. |
| </para> |
| </section> |
| |
| <section id='how-to-submit-a-change'> |
| <title>Submitting a Change to the Yocto Project</title> |
| |
| <para> |
| Contributions to the Yocto Project and OpenEmbedded are very welcome. |
| Because the system is extremely configurable and flexible, we recognize |
| that developers will want to extend, configure or optimize it for |
| their specific uses. |
| </para> |
| |
| <para> |
| The Yocto Project uses a mailing list and a patch-based workflow |
| that is similar to the Linux kernel but contains important |
| differences. |
| In general, a mailing list exists through which you can submit |
| patches. |
| You should send patches to the appropriate mailing list so that they |
| can be reviewed and merged by the appropriate maintainer. |
| The specific mailing list you need to use depends on the |
| location of the code you are changing. |
| Each component (e.g. layer) should have a |
| <filename>README</filename> file that indicates where to send |
| the changes and which process to follow. |
| </para> |
| |
| <para> |
| You can send the patch to the mailing list using whichever approach |
| you feel comfortable with to generate the patch. |
| Once sent, the patch is usually reviewed by the community at large. |
| If somebody has concerns with the patch, they will usually voice |
| their concern over the mailing list. |
| If a patch does not receive any negative reviews, the maintainer of |
| the affected layer typically takes the patch, tests it, and then |
| based on successful testing, merges the patch. |
| </para> |
| |
| <para id='figuring-out-the-mailing-list-to-use'> |
| The "poky" repository, which is the Yocto Project's reference build |
| environment, is a hybrid repository that contains several |
| individual pieces (e.g. BitBake, Metadata, documentation, |
| and so forth) built using the combo-layer tool. |
| The upstream location used for submitting changes varies by |
| component: |
| <itemizedlist> |
| <listitem><para> |
| <emphasis>Core Metadata:</emphasis> |
| Send your patch to the |
| <ulink url='http://lists.openembedded.org/mailman/listinfo/openembedded-core'>openembedded-core</ulink> |
| mailing list. For example, a change to anything under |
| the <filename>meta</filename> or |
| <filename>scripts</filename> directories should be sent |
| to this mailing list. |
| </para></listitem> |
| <listitem><para> |
| <emphasis>BitBake:</emphasis> |
| For changes to BitBake (i.e. anything under the |
| <filename>bitbake</filename> directory), send your patch |
| to the |
| <ulink url='http://lists.openembedded.org/mailman/listinfo/bitbake-devel'>bitbake-devel</ulink> |
| mailing list. |
| </para></listitem> |
| <listitem><para> |
| <emphasis>"meta-*" trees:</emphasis> |
| These trees contain Metadata. |
| Use the |
| <ulink url='https://lists.yoctoproject.org/listinfo/poky'>poky</ulink> |
| mailing list. |
| </para></listitem> |
| </itemizedlist> |
| </para> |
| |
| <para> |
| For changes to other layers hosted in the Yocto Project source |
| repositories (i.e. <filename>yoctoproject.org</filename>), tools, |
| and the Yocto Project documentation, use the |
| <ulink url='https://lists.yoctoproject.org/listinfo/yocto'>Yocto Project</ulink> |
| general mailing list. |
| <note> |
| Sometimes a layer's documentation specifies to use a |
| particular mailing list. |
| If so, use that list. |
| </note> |
| For additional recipes that do not fit into the core Metadata, you |
| should determine which layer the recipe should go into and submit |
| the change in the manner recommended by the documentation (e.g. |
| the <filename>README</filename> file) supplied with the layer. |
| If in doubt, please ask on the Yocto general mailing list or on |
| the openembedded-devel mailing list. |
| </para> |
| |
| <para> |
| You can also push a change upstream and request a maintainer to |
| pull the change into the component's upstream repository. |
| You do this by pushing to a contribution repository that is upstream. |
| See the |
| "<ulink url='&YOCTO_DOCS_REF_URL;#workflows'>Workflows</ulink>" |
| section in the Yocto Project Reference Manual for additional |
| concepts on working in the Yocto Project development environment. |
| </para> |
| |
| <para> |
| Two commonly used testing repositories exist for |
| OpenEmbedded-Core: |
| <itemizedlist> |
| <listitem><para> |
| <emphasis>"ross/mut" branch:</emphasis> |
| The "mut" (master-under-test) tree |
| exists in the <filename>poky-contrib</filename> repository |
| in the |
| <ulink url='&YOCTO_GIT_URL;'>Yocto Project source repositories</ulink>. |
| </para></listitem> |
| <listitem><para> |
| <emphasis>"master-next" branch:</emphasis> |
| This branch is part of the main |
| "poky" repository in the Yocto Project source repositories. |
| </para></listitem> |
| </itemizedlist> |
| Maintainers use these branches to test submissions prior to merging |
| patches. |
| Thus, you can get an idea of the status of a patch based on |
| whether the patch has been merged into one of these branches. |
| <note> |
| This system is imperfect and changes can sometimes get lost in the |
| flow. |
| Asking about the status of a patch or change is reasonable if the |
| change has been idle for a while with no feedback. |
| The Yocto Project does have plans to use |
| <ulink url='https://en.wikipedia.org/wiki/Patchwork_(software)'>Patchwork</ulink> |
| to track the status of patches and also to automatically preview |
| patches. |
| </note> |
| </para> |
| |
| <para> |
| The following sections provide procedures for submitting a change. |
| </para> |
| |
| <section id='pushing-a-change-upstream'> |
| <title>Using Scripts to Push a Change Upstream and Request a Pull</title> |
| |
| <para> |
| Follow this procedure to push a change to an upstream "contrib" |
| Git repository: |
| <note> |
| You can find general Git information on how to push a change |
| upstream in the |
| <ulink url='http://git-scm.com/book/en/v2/Distributed-Git-Distributed-Workflows'>Git Community Book</ulink>. |
| </note> |
| <orderedlist> |
| <listitem><para> |
| <emphasis>Make Your Changes Locally:</emphasis> |
| Make your changes in your local Git repository. |
| You should make small, controlled, isolated changes. |
| Keeping changes small and isolated aids review, |
| makes merging/rebasing easier and keeps the change |
| history clean should anyone need to refer to it in |
| future. |
| </para></listitem> |
| <listitem><para> |
| <emphasis>Stage Your Changes:</emphasis> |
| Stage your changes by using the <filename>git add</filename> |
| command on each file you changed. |
| </para></listitem> |
| <listitem><para id='making-sure-you-have-correct-commit-information'> |
| <emphasis>Commit Your Changes:</emphasis> |
| Commit the change by using the |
| <filename>git commit</filename> command. |
| Make sure your commit information follows standards by |
| following these accepted conventions: |
| <itemizedlist> |
| <listitem><para> |
| Be sure to include a "Signed-off-by:" line in the |
| same style as required by the Linux kernel. |
| Adding this line signifies that you, the submitter, |
| have agreed to the Developer's Certificate of |
| Origin 1.1 as follows: |
| <literallayout class='monospaced'> |
| Developer's Certificate of Origin 1.1 |
| |
| By making a contribution to this project, I certify that: |
| |
| (a) The contribution was created in whole or in part by me and I |
| have the right to submit it under the open source license |
| indicated in the file; or |
| |
| (b) The contribution is based upon previous work that, to the best |
| of my knowledge, is covered under an appropriate open source |
| license and I have the right under that license to submit that |
| work with modifications, whether created in whole or in part |
| by me, under the same open source license (unless I am |
| permitted to submit under a different license), as indicated |
| in the file; or |
| |
| (c) The contribution was provided directly to me by some other |
| person who certified (a), (b) or (c) and I have not modified |
| it. |
| |
| (d) I understand and agree that this project and the contribution |
| are public and that a record of the contribution (including all |
| personal information I submit with it, including my sign-off) is |
| maintained indefinitely and may be redistributed consistent with |
| this project or the open source license(s) involved. |
| </literallayout> |
| </para></listitem> |
| <listitem><para> |
| Provide a single-line summary of the change. |
| and, |
| if more explanation is needed, provide more |
| detail in the body of the commit. |
| This summary is typically viewable in the |
| "shortlist" of changes. |
| Thus, providing something short and descriptive |
| that gives the reader a summary of the change is |
| useful when viewing a list of many commits. |
| You should prefix this short description with the |
| recipe name (if changing a recipe), or else with |
| the short form path to the file being changed. |
| </para></listitem> |
| <listitem><para> |
| For the body of the commit message, provide |
| detailed information that describes what you |
| changed, why you made the change, and the approach |
| you used. |
| It might also be helpful if you mention how you |
| tested the change. |
| Provide as much detail as you can in the body of |
| the commit message. |
| <note> |
| You do not need to provide a more detailed |
| explanation of a change if the change is |
| minor to the point of the single line |
| summary providing all the information. |
| </note> |
| </para></listitem> |
| <listitem><para> |
| If the change addresses a specific bug or issue |
| that is associated with a bug-tracking ID, |
| include a reference to that ID in your detailed |
| description. |
| For example, the Yocto Project uses a specific |
| convention for bug references - any commit that |
| addresses a specific bug should use the following |
| form for the detailed description. |
| Be sure to use the actual bug-tracking ID from |
| Bugzilla for |
| <replaceable>bug-id</replaceable>: |
| <literallayout class='monospaced'> |
| Fixes [YOCTO #<replaceable>bug-id</replaceable>] |
| |
| <replaceable>detailed description of change</replaceable> |
| </literallayout> |
| </para></listitem> |
| </itemizedlist> |
| </para></listitem> |
| <listitem><para> |
| <emphasis>Push Your Commits to a "Contrib" Upstream:</emphasis> |
| If you have arranged for permissions to push to an |
| upstream contrib repository, push the change to that |
| repository: |
| <literallayout class='monospaced'> |
| $ git push <replaceable>upstream_remote_repo</replaceable> <replaceable>local_branch_name</replaceable> |
| </literallayout> |
| For example, suppose you have permissions to push into the |
| upstream <filename>meta-intel-contrib</filename> |
| repository and you are working in a local branch named |
| <replaceable>your_name</replaceable><filename>/README</filename>. |
| The following command pushes your local commits to the |
| <filename>meta-intel-contrib</filename> upstream |
| repository and puts the commit in a branch named |
| <replaceable>your_name</replaceable><filename>/README</filename>: |
| <literallayout class='monospaced'> |
| $ git push meta-intel-contrib <replaceable>your_name</replaceable>/README |
| </literallayout> |
| </para></listitem> |
| <listitem><para id='push-determine-who-to-notify'> |
| <emphasis>Determine Who to Notify:</emphasis> |
| Determine the maintainer or the mailing list |
| that you need to notify for the change.</para> |
| |
| <para>Before submitting any change, you need to be sure |
| who the maintainer is or what mailing list that you need |
| to notify. |
| Use either these methods to find out: |
| <itemizedlist> |
| <listitem><para> |
| <emphasis>Maintenance File:</emphasis> |
| Examine the <filename>maintainers.inc</filename> |
| file, which is located in the |
| <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink> |
| at |
| <filename>meta/conf/distro/include</filename>, |
| to see who is responsible for code. |
| </para></listitem> |
| <listitem><para> |
| <emphasis>Search by File:</emphasis> |
| Using <ulink url='&YOCTO_DOCS_REF_URL;#git'>Git</ulink>, |
| you can enter the following command to bring up a |
| short list of all commits against a specific file: |
| <literallayout class='monospaced'> |
| git shortlog -- <replaceable>filename</replaceable> |
| </literallayout> |
| Just provide the name of the file for which you |
| are interested. |
| The information returned is not ordered by history |
| but does include a list of everyone who has |
| committed grouped by name. |
| From the list, you can see who is responsible for |
| the bulk of the changes against the file. |
| </para></listitem> |
| <listitem><para> |
| <emphasis>Examine the List of Mailing Lists:</emphasis> |
| For a list of the Yocto Project and related mailing |
| lists, see the |
| "<ulink url='&YOCTO_DOCS_REF_URL;#resources-mailinglist'>Mailing lists</ulink>" |
| section in the Yocto Project Reference Manual. |
| </para></listitem> |
| </itemizedlist> |
| </para></listitem> |
| <listitem><para> |
| <emphasis>Make a Pull Request:</emphasis> |
| Notify the maintainer or the mailing list that you have |
| pushed a change by making a pull request.</para> |
| |
| <para>The Yocto Project provides two scripts that |
| conveniently let you generate and send pull requests to the |
| Yocto Project. |
| These scripts are <filename>create-pull-request</filename> |
| and <filename>send-pull-request</filename>. |
| You can find these scripts in the |
| <filename>scripts</filename> directory within the |
| <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink> |
| (e.g. <filename>~/poky/scripts</filename>). |
| </para> |
| |
| <para>Using these scripts correctly formats the requests |
| without introducing any whitespace or HTML formatting. |
| The maintainer that receives your patches either directly |
| or through the mailing list needs to be able to save and |
| apply them directly from your emails. |
| Using these scripts is the preferred method for sending |
| patches.</para> |
| |
| <para>First, create the pull request. |
| For example, the following command runs the script, |
| specifies the upstream repository in the contrib directory |
| into which you pushed the change, and provides a subject |
| line in the created patch files: |
| <literallayout class='monospaced'> |
| $ ~/poky/scripts/create-pull-request -u meta-intel-contrib -s "Updated Manual Section Reference in README" |
| </literallayout> |
| Running this script forms |
| <filename>*.patch</filename> files in a folder named |
| <filename>pull-</filename><replaceable>PID</replaceable> |
| in the current directory. |
| One of the patch files is a cover letter.</para> |
| |
| <para>Before running the |
| <filename>send-pull-request</filename> script, you must |
| edit the cover letter patch to insert information about |
| your change. |
| After editing the cover letter, send the pull request. |
| For example, the following command runs the script and |
| specifies the patch directory and email address. |
| In this example, the email address is a mailing list: |
| <literallayout class='monospaced'> |
| $ ~/poky/scripts/send-pull-request -p ~/meta-intel/pull-10565 -t meta-intel@yoctoproject.org |
| </literallayout> |
| You need to follow the prompts as the script is |
| interactive. |
| <note> |
| For help on using these scripts, simply provide the |
| <filename>-h</filename> argument as follows: |
| <literallayout class='monospaced'> |
| $ poky/scripts/create-pull-request -h |
| $ poky/scripts/send-pull-request -h |
| </literallayout> |
| </note> |
| </para></listitem> |
| </orderedlist> |
| </para> |
| </section> |
| |
| <section id='submitting-a-patch'> |
| <title>Using Email to Submit a Patch</title> |
| |
| <para> |
| You can submit patches without using the |
| <filename>create-pull-request</filename> and |
| <filename>send-pull-request</filename> scripts described in the |
| previous section. |
| However, keep in mind, the preferred method is to use the scripts. |
| </para> |
| |
| <para> |
| Depending on the components changed, you need to submit the email |
| to a specific mailing list. |
| For some guidance on which mailing list to use, see the |
| <link linkend='figuring-out-the-mailing-list-to-use'>beginning</link> |
| of this section. |
| For a description of all the available mailing lists, see the |
| "<ulink url='&YOCTO_DOCS_REF_URL;#resources-mailinglist'>Mailing Lists</ulink>" |
| section in the Yocto Project Reference Manual. |
| </para> |
| |
| <para> |
| Here is the general procedure on how to submit a patch through |
| email without using the scripts: |
| <orderedlist> |
| <listitem><para> |
| <emphasis>Make Your Changes Locally:</emphasis> |
| Make your changes in your local Git repository. |
| You should make small, controlled, isolated changes. |
| Keeping changes small and isolated aids review, |
| makes merging/rebasing easier and keeps the change |
| history clean should anyone need to refer to it in |
| future. |
| </para></listitem> |
| <listitem><para> |
| <emphasis>Stage Your Changes:</emphasis> |
| Stage your changes by using the <filename>git add</filename> |
| command on each file you changed. |
| </para></listitem> |
| <listitem><para> |
| <emphasis>Commit Your Changes:</emphasis> |
| Commit the change by using the |
| <filename>git commit --signoff</filename> command. |
| Using the <filename>--signoff</filename> option identifies |
| you as the person making the change and also satisfies |
| the Developer's Certificate of Origin (DCO) shown earlier. |
| </para> |
| |
| <para>When you form a commit, you must follow certain |
| standards established by the Yocto Project development |
| team. |
| See |
| <link linkend='making-sure-you-have-correct-commit-information'>Step 3</link> |
| in the previous section for information on how to |
| provide commit information that meets Yocto Project |
| commit message standards. |
| </para></listitem> |
| <listitem><para> |
| <emphasis>Format the Commit:</emphasis> |
| Format the commit into an email message. |
| To format commits, use the |
| <filename>git format-patch</filename> command. |
| When you provide the command, you must include a revision |
| list or a number of patches as part of the command. |
| For example, either of these two commands takes your most |
| recent single commit and formats it as an email message in |
| the current directory: |
| <literallayout class='monospaced'> |
| $ git format-patch -1 |
| </literallayout> |
| or |
| <literallayout class='monospaced'> |
| $ git format-patch HEAD~ |
| </literallayout></para> |
| |
| <para>After the command is run, the current directory |
| contains a numbered <filename>.patch</filename> file for |
| the commit.</para> |
| |
| <para>If you provide several commits as part of the |
| command, the <filename>git format-patch</filename> command |
| produces a series of numbered files in the current |
| directory – one for each commit. |
| If you have more than one patch, you should also use the |
| <filename>--cover</filename> option with the command, |
| which generates a cover letter as the first "patch" in |
| the series. |
| You can then edit the cover letter to provide a |
| description for the series of patches. |
| For information on the |
| <filename>git format-patch</filename> command, |
| see <filename>GIT_FORMAT_PATCH(1)</filename> displayed |
| using the <filename>man git-format-patch</filename> |
| command. |
| <note> |
| If you are or will be a frequent contributor to the |
| Yocto Project or to OpenEmbedded, you might consider |
| requesting a contrib area and the necessary associated |
| rights. |
| </note> |
| </para></listitem> |
| <listitem><para> |
| <emphasis>Import the Files Into Your Mail Client:</emphasis> |
| Import the files into your mail client by using the |
| <filename>git send-email</filename> command. |
| <note> |
| In order to use <filename>git send-email</filename>, |
| you must have the proper Git packages installed on |
| your host. |
| For Ubuntu, Debian, and Fedora the package is |
| <filename>git-email</filename>. |
| </note></para> |
| |
| <para>The <filename>git send-email</filename> command |
| sends email by using a local or remote Mail Transport Agent |
| (MTA) such as <filename>msmtp</filename>, |
| <filename>sendmail</filename>, or through a direct |
| <filename>smtp</filename> configuration in your Git |
| <filename>~/.gitconfig</filename> file. |
| If you are submitting patches through email only, it is |
| very important that you submit them without any whitespace |
| or HTML formatting that either you or your mailer |
| introduces. |
| The maintainer that receives your patches needs to be able |
| to save and apply them directly from your emails. |
| A good way to verify that what you are sending will be |
| applicable by the maintainer is to do a dry run and send |
| them to yourself and then save and apply them as the |
| maintainer would.</para> |
| |
| <para>The <filename>git send-email</filename> command is |
| the preferred method for sending your patches using |
| email since there is no risk of compromising whitespace |
| in the body of the message, which can occur when you use |
| your own mail client. |
| The command also has several options that let you |
| specify recipients and perform further editing of the |
| email message. |
| For information on how to use the |
| <filename>git send-email</filename> command, |
| see <filename>GIT-SEND-EMAIL(1)</filename> displayed using |
| the <filename>man git-send-email</filename> command. |
| </para></listitem> |
| </orderedlist> |
| </para> |
| </section> |
| </section> |
| </chapter> |
| <!-- |
| vim: expandtab tw=80 ts=4 |
| --> |