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. You should send patches to the appropriate mailing list so that they can be reviewed and merged by the appropriate maintainer.
Before submitting any change, be sure to find out who you should be notifying. Several methods exist through which you find out who you should be copying or notifying:
Maintenance File:
Examine the maintainers.inc
file, which is
located in the
Source Directory
at meta-yocto/conf/distro/include
, to
see who is responsible for code.
Board Support Package (BSP) README Files:
For BSP maintainers of supported BSPs, you can examine
individual BSP README
files.
In addition, some layers (such as the meta-intel
layer),
include a MAINTAINERS
file which contains
a list of all supported BSP maintainers for that layer.
Search by File: Using Git, you can enter the following command to bring up a short list of all commits against a specific file:
git shortlog -- filename
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 all committers grouped by name. From the list, you can see who is responsible for the bulk of the changes against the file.
For a list of the Yocto Project and related mailing lists, see the "Mailing lists" section in the Yocto Project Reference Manual.
Here is some guidance on which mailing list to use for what type of change:
For changes to the core
Metadata, send your patch to the
openembedded-core mailing list.
For example, a change to anything under the meta
or
scripts
directories
should be sent to this mailing list.
For changes to BitBake (anything under the bitbake
directory), send your patch to the
bitbake-devel mailing list.
For changes to meta-yocto
, send your patch to the
poky mailing list.
For changes to other layers hosted on
yoctoproject.org
(unless the
layer's documentation specifies otherwise), tools, and Yocto Project
documentation, use the
yocto mailing list.
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. README) supplied with the layer. If in doubt, please ask on the yocto or openembedded-devel mailing lists.
When you send a patch, 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:
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.
In a collaborative environment, it is necessary to have some sort of standard or method through which you submit changes. Otherwise, things could get quite chaotic. One general practice to follow is to make small, controlled changes. Keeping changes small and isolated aids review, makes merging/rebasing easier and keeps the change history clean when anyone needs to refer to it in future.
When you make a commit, you must follow certain standards established by the OpenEmbedded and Yocto Project development teams. For each commit, you must provide a single-line summary of the change and you should almost always provide a more detailed description of what you did (i.e. the body of the commit message). The only exceptions for not providing a detailed description would be if your change is a simple, self-explanatory change that needs no further description beyond the summary. Here are the guidelines for composing a commit message:
bug-id
Provide a single-line, short summary of the change. 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. This short description should be prefixed by the recipe name (if changing a recipe), or else the short form path to the file being changed.
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 may 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.
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:
Fixes [YOCTO #bug-id
]detailed description of change
You can find more guidance on creating well-formed commit messages at this OpenEmbedded wiki page: http://www.openembedded.org/wiki/Commit_Patch_Message_Guidelines.
The next two sections describe general instructions for both pushing changes upstream and for submitting changes as patches.