I'm going to propose the following partial rewrite of the "How to submit a change" section of the manual:

"""
3.9. How to Submit a Change

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.

3.9.1 General Overview

The project uses a mailing list and patch based workflow, similar to the Linux Kernel but there are important differences too. In general, there will be a mailing list to submit the patches to, the correct mailing list will depend on the location of the code you're changing. Each component (e.g. a layer) should have a README indicating where to send the changes and which process to follow.

You can send the patch to the mailing list using whichever approach your feel comfortable with to generate the patch. The patch will usually be reviewed by the community at large and if someone has concerns with the patch, you'll usually hear about them. The layer maintainers will usually pick up patches which haven't had negative reviews and test them, usually in batches and then merge them if testing is successful. There are sections below which describe general instructions for both pushing changes upstream and for submitting changes as patches.

This system is imperfect and patches can sometimes get lost in the system. Asking about the status of a patch is reasonable if its sat for a while with no feedback. The project does have plans to use patchwork to track the status of patches and also to do automated pre-review of patches, there is ongoing work in this area.

Specifically to OpenEmbedded-Core, there are two commonly used testing trees, "mut" (master-under-test), found as the "ross/mut" branch in poky-contrib and the master-next branch of the main repository. These branches are used by the maintainers to test submissions prior to merging of patches. You can therefore get some idea of the status of a patch if its in one of these branches.

3.9.2 Submissions to Poky

The poky repository (the Yocto Project's reference build environment) is a hybrid repository combining several individual pieces, Bitbake, OpenEmbedded-Core, meta-yocto and documentation built using the combo-layer tool. The upstream location to submit changes to varies by component:

    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.

    meta-yocto-bsp and meta-poky come from the meta-yocto repository so your changes would go to the poky mailing list.

3.9.3 Submissions to other layers

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.


3.9.4 Patch Submission Details

When submitting any change, you can check 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-poky/conf/distro/include, to see who is responsible for code.

    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.


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.

3.9.5. Using Scripts to Push a Change Upstream and Request a Pull

[unchanged]

3.9.6. Using Email to Submit a Patch

[unchanged]
"""

Does that address some of your questions? Sadly patchwork isn't quite there but I've hinted its a work in progress and we can tweak the manual when it is available.

Yes, I think that is an improvement. However there is a lot of referencing to other sections/documents, these should really be links.

For example, as I'm not a kernel developer I don't know their procedures, linking to a page detailing their procedures would be _very_ helpful.

You are also referencing sections further down, they should probably be links as well, but I'm guessing this is part of the details of that proposal you are working on.

Another important piece I find missing is how to find that document, or that part of the document, as it requires some searching and it was not clear to me I was supposed to search in that document.

(In reply to comment #1)

> 
> 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:

RP,

(this is not related to the bug itself)
patchtest test suite has a check for empty commit descriptions, so if you think the commit description is optional (because you used 'should' instead of 'must', then the check must be skipped.

What I have seen so far is that recipes upgrades do not add the description, also the most active commit pushers sometimes omit the the latter.

Linus and Richard, 

See http://www.yoctoproject.org/docs/2.3/dev-manual/dev-manual.html#how-to-submit-a-change in the YP Development Manual for the updated section on submitting changes/patches to the project.  I did a fair amount of rewriting given Richard's nice base suggestion.  

I don't know where to link for parallel Linux kernel procedures regarding submitting patches?  If someone knows that tell me and I can get a reference in there.

Regarding finding this topic.... I guess all I can say is searching for keywords like "patch", "submitting", etc. is the best thing to do.  We do have the Mega-manual (http://www.yoctoproject.org/docs/current/mega-manual/mega-manual.html), which is a large manual consisting of concatenated HTML versions of the core YP manual set.  I am pretty sure that our main intent of even creating that manual was for search purposes.

Anyway, please review these changes and let me know of any updates I need to apply.

Thanks,
Scott

Hi, 

No feedback since mid-January.  I am marking as RESOLVED and setting the doc flag to "done."

Scott