sysmo-bts
/
generic-poky
9
0
Fork 0
Code Pull Requests Releases Activity

dev-manual: tidy up "How to Submit a Change" section 

* Change some of the language and patch submission directions to
  correctly represent how we work together with OpenEmbedded (this
  changed with the introduction of OE-Core a few releases ago).
* Correct --help option to -h for pull request scripts
* Clarify commit message guidelines
* Touch up a few other bits and pieces

Fixes [YOCTO #2671].

(From yocto-docs rev: 3170ce5e0757951afee13207c117316e33449b39)

Signed-off-by: Paul Eggleton <paul.eggleton@linux.intel.com>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
This commit is contained in:
Paul Eggleton 2012-07-02 10:20:20 +01:00 committed by Richard Purdie
parent dd5f6ae551
commit 257e61a2cb
1 changed files with 59 additions and 60 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

119
documentation/dev-manual/dev-manual-newbie.xml
View File

@ -874,54 +874,53 @@
<listitem><para>Submit the bug by clicking the "Submit Bug" button.</para></listitem>
</orderedlist>
</para>
<note>
Bugs in the Yocto Project Bugzilla follow naming convention:
<filename>[YOCTO #&lt;number&gt;]</filename>, where <filename>&lt;number&gt;</filename> is the
assigned defect ID used in Bugzilla.
So, for example, a valid way to refer to a defect would be <filename>[YOCTO #1011]</filename>.
This convention becomes important if you are submitting patches against the Yocto Project
code itself.
</note>
</section>
<section id='how-to-submit-a-change'>
<title>How to Submit a Change</title>
<para>
Contributions to the Yocto Project are very welcome.
Because the Yocto Project is extremely configurable and flexible, we recognize that developers
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 Yocto Project mailing list to get them
in front of the Yocto Project Maintainer.
For a list of the Yocto Project mailing lists, see the
You should send patches to the appropriate mailing list so that they
can be reviewed and merged by the appropriate maintainer.
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>
<para>
The following is some guidance on which mailing list to use for what type of defect:
The following is some guidance on which mailing list to use for what type of change:
<itemizedlist>
<listitem><para>For defects against the Yocto Project build system Poky, send
your patch to the
<ulink url='&YOCTO_LISTS_URL;/listinfo/poky'></ulink> mailing list.
This mailing list corresponds to issues that are not specific to the Yocto Project but
are part of the OE-core.
For example, a defect against anything in the <filename>meta</filename> layer
or the BitBake Manual could be sent to this mailing list.</para></listitem>
<listitem><para>For defects against Yocto-specific layers, tools, and Yocto Project
documentation use the
<ulink url='&YOCTO_LISTS_URL;/listinfo/yocto'></ulink> mailing list.
This mailing list corresponds to Yocto-specific areas such as
<filename>meta-yocto</filename>, <filename>meta-intel</filename>,
<filename>linux-yocto</filename>, and <filename>documentation</filename>.</para></listitem>
<listitem><para>For changes to the core metadata, send your patch to the
<ulink url='&OE_LISTS_URL;/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>For changes to BitBake (anything under the <filename>bitbake</filename>
directory), send your patch to the
<ulink url='&OE_LISTS_URL;/listinfo/bitbake-devel'>bitbake-devel</ulink> mailing list.</para></listitem>
<listitem><para>For changes to <filename>meta-yocto</filename>, send your patch to the
<ulink url='&YOCTO_LISTS_URL;/listinfo/poky'>poky</ulink> mailing list.</para></listitem>
<listitem><para>For changes to other layers hosted on yoctoproject.org (unless the
layer's documentation specifies otherwise), tools, and Yocto Project
documentation, use the
<ulink url='&YOCTO_LISTS_URL;/listinfo/yocto'>yocto</ulink> mailing list.</para></listitem>
<listitem><para>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
<ulink url='&YOCTO_LISTS_URL;/listinfo/yocto'>yocto</ulink> or
<ulink url='&OE_LISTS_URL;/listinfo/openembedded-devel'>openembedded-devel</ulink>
mailing lists.</para></listitem>
</itemizedlist>
</para>
<para>
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 the developer has agreed to the Developer's Certificate of Origin 1.1
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
@ -950,52 +949,52 @@
maintained indefinitely and may be redistributed consistent with
this project or the open source license(s) involved.
</literallayout>
A Poky contributions tree (<filename>poky-contrib</filename>,
<filename>git://git.yoctoproject.org/poky-contrib.git</filename>)
exists for contributors to stage contributions.
If people desire such access, please ask on the mailing list.
Usually, the Yocto Project team will grant access to anyone with a proven track
record of good patches.
</para>
<para>
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 to the
Yocto Project.
Keeping changes small and isolated lets you best keep pace with future Yocto Project changes.
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.
</para>
<para>
When you create a commit, you must follow certain standards established by the
Yocto Project development team.
For each commit, you must provide a single-line summary of the change and you
almost always provide a more detailed description of what you did (i.e. the body
of the commit).
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 description.
Here are the Yocto Project commit message guidelines:
Here are the guidelines for composing a commit message:
<itemizedlist>
<listitem><para>Provide a single-line, short summary of the change.
This summary is typically viewable by source control systems.
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 should be prefixed by the recipe name (if changing a recipe), or
else 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.
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.
</para></listitem>
<listitem><para>If the change addresses a specific bug or issue that is
associated with a bug-tracking ID, prefix your detailed description
with the bug or issue ID.
For example, the Yocto Project tracks bugs using a bug-naming convention.
Any commits that address a bug must start with the bug ID in the description
as follows:
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 include the
bug ID in the description (typically at the end) as follows:
<literallayout class='monospaced'>
YOCTO #&lt;bug-id&gt;: &lt;Detailed description of commit&gt;
&lt;detailed description of change&gt;
[YOCTO #&lt;bug-id&gt;]
</literallayout></para></listitem>
Where &lt;bug-id&gt; is replaced with the specific bug ID from the
Yocto Project Bugzilla instance.
</itemizedlist>
</para>
@ -1016,11 +1015,11 @@
The basic flow for pushing a change to an upstream "contrib" Git repository is as follows:
<itemizedlist>
<listitem><para>Make your changes in your local Git repository.</para></listitem>
<listitem><para>Stage your commit (or change) by using the <filename>git add</filename>
command.</para></listitem>
<listitem><para>Stage your changes by using the <filename>git add</filename>
command on each file you changed.</para></listitem>
<listitem><para>Commit the change by using the <filename>git commit</filename>
command and push it to the "contrib" repository.
Be sure to provide a commit message that follows the project’s commit standards
Be sure to provide a commit message that follows the project’s commit message standards
as described earlier.</para></listitem>
<listitem><para>Notify the maintainer that you have pushed a change by making a pull
request.
@ -1031,10 +1030,10 @@
You can find these scripts in the <filename>scripts</filename> directory of the
Yocto Project file structure.</para>
<para>For help on using these scripts, simply provide the
<filename>--help</filename> argument as follows:
<filename>-h</filename> argument as follows:
<literallayout class='monospaced'>
$ ~/poky/scripts/create-pull-request --help
$ ~/poky/scripts/send-pull-request --help
$ ~/poky/scripts/create-pull-request -h
$ ~/poky/scripts/send-pull-request -h
</literallayout></para></listitem>
</itemizedlist>
</para>
@ -1054,8 +1053,8 @@
Here is a general procedure:
<itemizedlist>
<listitem><para>Make your changes in your local Git repository.</para></listitem>
<listitem><para>Stage your commit (or change) by using the <filename>git add</filename>
command.</para></listitem>
<listitem><para>Stage your changes by using the <filename>git add</filename>
command on each file you changed.</para></listitem>
<listitem><para>Commit the change by using the
<filename>git commit --signoff</filename> command.
Using the <filename>--signoff</filename> option identifies you as the person