diff options
Diffstat (limited to 'documentation/dev-manual/dev-manual-newbie.xml')
| -rw-r--r-- | documentation/dev-manual/dev-manual-newbie.xml | 990 |
1 files changed, 0 insertions, 990 deletions
diff --git a/documentation/dev-manual/dev-manual-newbie.xml b/documentation/dev-manual/dev-manual-newbie.xml deleted file mode 100644 index 68c8d9bbea6..00000000000 --- a/documentation/dev-manual/dev-manual-newbie.xml +++ /dev/null @@ -1,990 +0,0 @@ -<!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_GS_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_GS_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_GS_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_GS_URL;#workflows'>Workflows</ulink>" - section in the Getting Started With Yocto Project 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_GS_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 ---> |