diff --git a/documentation/dev-manual/dev-manual-newbie.xml b/documentation/dev-manual/dev-manual-newbie.xml
index 75c992f16b..4fd0d3a60c 100644
--- a/documentation/dev-manual/dev-manual-newbie.xml
+++ b/documentation/dev-manual/dev-manual-newbie.xml
@@ -1394,83 +1394,182 @@
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-poky/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:
-
+
+ Overview
+
+
+ The Yocto Project uses a mailing list and 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.
+ 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
+ README file that indicates where to send
+ the changes and which process to follow.
+
+
+
+ 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.
+
+
+
+ Specific to OpenEmbedded-Core, two commonly used testing trees
+ exist:
+
+
+ "ross/mut" branch:
+ The "mut" (master-under-test) tree
+ exists in the poky-contrib repository
+ in the
+ Yocto Project source repositories.
+
+
+ "master-next" branch:
+ This branch is part of the main
+ "poky" repository in the Yocto Project source repositories.
+
+
+ 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.
+
+
+
+ This system is imperfect and patches can sometimes get lost in the
+ flow.
+ Asking about the status of a patch is reasonable if the patch
+ has been idle for a while with no feedback.
+ The Yocto Project does have plans to use
+ Patchwork
+ to track the status of patches and also to automatically preview
+ patches.
+
+
+
+ The following sections provide general instructions for both
+ pushing changes upstream and for submitting changes as patches.
+
+
+
+
+ Submissions to Poky
+
+
+ The "poky" repository, which is the Yocto Project's reference build
+ environment, is a hybrid repository that contains several
+ individual pieces (e.g. BitBake, OpenEmbedded-Core, meta-yocto,
+ documentation, and so forth) built using the combo-layer tool.
+ The upstream location used for submitting changes varies by
+ component:
+
+
+ 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.
+
+
+ BitBake:
+ For changes to BitBake (i.e. anything under the
+ bitbake directory), send your patch
+ to the
+ bitbake-devel
+ mailing list.
+
+
+ "meta-yocto-bsp" and "meta-poky" trees:
+ These trees are
+ part of the "meta-yocto" repository in the Yocto Project
+ source repositories.
+ Use the
+ poky
+ mailing list.
+
+
+
+
+
+
+ Submissions to Other Layers
+
+
+ For changes to other layers hosted in the Yocto Project source
+ repositories (i.e. yoctoproject.org), tools,
+ and the Yocto Project documentation, use the
+ Yocto Project
+ general mailing list.
+
+ Sometimes a layer's documentation specifies to use a
+ particular mailing list.
+ If so, use that 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.
+ the README file) supplied with the layer.
+ If in doubt, please ask on the Yocto general mailing list or on
+ the openembedded-devel mailing list.
+
+
+
+
+ Patch Submission Details
+
+
+ When submitting any change, you can check who you should be
+ notifying.
+ Use either of these methods to find out:
+
+
+ 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.
-
-
-
+
+ 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.
-
+
+ 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-poky, 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:
-
+
+ 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:
@@ -1496,68 +1595,75 @@
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.
-
+
+ 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 should
+ anyone need 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:
-
- 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:
-
+
+ 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:
+
+
+ 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.
+ 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.
+
+
+ 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.
+
+
+ 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
-
+
+
Where bug-id is replaced with the
specific bug ID from the Yocto Project Bugzilla instance.
-
-
+
+
-
- You can find more guidance on creating well-formed commit messages at this OpenEmbedded
- wiki page:
- .
-
-
-
- The next two sections describe general instructions for both pushing
- changes upstream and for submitting changes as patches.
-
+
+ You can find more guidance on creating well-formed commit messages
+ at this OpenEmbedded wiki page:
+ .
+
+
Using Scripts to Push a Change Upstream and Request a Pull