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

117
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> <listitem><para>Submit the bug by clicking the "Submit Bug" button.</para></listitem>
</orderedlist> </orderedlist>
</para> </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>
<section id='how-to-submit-a-change'> <section id='how-to-submit-a-change'>
<title>How to Submit a Change</title> <title>How to Submit a Change</title>
<para> <para>
Contributions to the Yocto Project are very welcome. Contributions to the Yocto Project and OpenEmbedded are very welcome.
Because the Yocto Project is extremely configurable and flexible, we recognize that developers Because the system is extremely configurable and flexible, we recognize that developers
will want to extend, configure or optimize it for their specific uses. 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 You should send patches to the appropriate mailing list so that they
in front of the Yocto Project Maintainer. can be reviewed and merged by the appropriate maintainer.
For a list of the Yocto Project mailing lists, see the 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 "<ulink url='&YOCTO_DOCS_REF_URL;#resources-mailinglist'>Mailing lists</ulink>" section in
The Yocto Project Reference Manual. The Yocto Project Reference Manual.
</para> </para>
<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> <itemizedlist>
<listitem><para>For defects against the Yocto Project build system Poky, send <listitem><para>For changes to the core metadata, send your patch to the
your patch to the <ulink url='&OE_LISTS_URL;/listinfo/openembedded-core'>openembedded-core</ulink> mailing list.
<ulink url='&YOCTO_LISTS_URL;/listinfo/poky'></ulink> mailing list. For example, a change to anything under the <filename>meta</filename> or
This mailing list corresponds to issues that are not specific to the Yocto Project but <filename>scripts</filename> directories
are part of the OE-core. should be sent to this mailing list.</para></listitem>
For example, a defect against anything in the <filename>meta</filename> layer <listitem><para>For changes to BitBake (anything under the <filename>bitbake</filename>
or the BitBake Manual could be sent to this mailing list.</para></listitem> directory), send your patch to the
<listitem><para>For defects against Yocto-specific layers, tools, and Yocto Project <ulink url='&OE_LISTS_URL;/listinfo/bitbake-devel'>bitbake-devel</ulink> mailing list.</para></listitem>
documentation use the <listitem><para>For changes to <filename>meta-yocto</filename>, send your patch to the
<ulink url='&YOCTO_LISTS_URL;/listinfo/yocto'></ulink> mailing list. <ulink url='&YOCTO_LISTS_URL;/listinfo/poky'>poky</ulink> mailing list.</para></listitem>
This mailing list corresponds to Yocto-specific areas such as <listitem><para>For changes to other layers hosted on yoctoproject.org (unless the
<filename>meta-yocto</filename>, <filename>meta-intel</filename>, layer's documentation specifies otherwise), tools, and Yocto Project
<filename>linux-yocto</filename>, and <filename>documentation</filename>.</para></listitem> 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> </itemizedlist>
</para> </para>
<para> <para>
When you send a patch, be sure to include a "Signed-off-by:" When you send a patch, be sure to include a "Signed-off-by:"
line in the same style as required by the Linux kernel. 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: as follows:
<literallayout class='monospaced'> <literallayout class='monospaced'>
Developer's Certificate of Origin 1.1 Developer's Certificate of Origin 1.1
@ -950,52 +949,52 @@
maintained indefinitely and may be redistributed consistent with maintained indefinitely and may be redistributed consistent with
this project or the open source license(s) involved. this project or the open source license(s) involved.
</literallayout> </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>
<para> <para>
In a collaborative environment, it is necessary to have some sort of standard In a collaborative environment, it is necessary to have some sort of standard
or method through which you submit changes. or method through which you submit changes.
Otherwise, things could get quite chaotic. Otherwise, things could get quite chaotic.
One general practice to follow is to make small, controlled changes to the One general practice to follow is to make small, controlled changes.
Yocto Project. Keeping changes small and isolated aids review, makes merging/rebasing easier
Keeping changes small and isolated lets you best keep pace with future Yocto Project changes. and keeps the change history clean when anyone needs to refer to it in future.
</para> </para>
<para> <para>
When you create a commit, you must follow certain standards established by the When you make a commit, you must follow certain standards established by the
Yocto Project development team. OpenEmbedded and Yocto Project development teams.
For each commit, you must provide a single-line summary of the change and you 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 should almost always provide a more detailed description of what you did (i.e.
of the commit). the body of the commit message).
The only exceptions for not providing a detailed description would be if your The only exceptions for not providing a detailed description would be if your
change is a simple, self-explanatory change that needs no description. 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> <itemizedlist>
<listitem><para>Provide a single-line, short summary of the change. <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 Thus, providing something short and descriptive that gives the reader
a summary of the change is useful when viewing a list of many commits. 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> </para></listitem>
<listitem><para>For the body of the commit message, provide detailed information <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 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. Provide as much detail as you can in the body of the commit message.
</para></listitem> </para></listitem>
<listitem><para>If the change addresses a specific bug or issue that is <listitem><para>If the change addresses a specific bug or issue that is
associated with a bug-tracking ID, prefix your detailed description associated with a bug-tracking ID, include a reference to that ID in
with the bug or issue ID. your detailed description.
For example, the Yocto Project tracks bugs using a bug-naming convention. For example, the Yocto Project uses a specific convention for bug
Any commits that address a bug must start with the bug ID in the description references - any commit that addresses a specific bug should include the
as follows: bug ID in the description (typically at the end) as follows:
<literallayout class='monospaced'> <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> </literallayout></para></listitem>
Where &lt;bug-id&gt; is replaced with the specific bug ID from the
Yocto Project Bugzilla instance.
</itemizedlist> </itemizedlist>
</para> </para>
@ -1016,11 +1015,11 @@
The basic flow for pushing a change to an upstream "contrib" Git repository is as follows: The basic flow for pushing a change to an upstream "contrib" Git repository is as follows:
<itemizedlist> <itemizedlist>
<listitem><para>Make your changes in your local Git repository.</para></listitem> <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> <listitem><para>Stage your changes by using the <filename>git add</filename>
command.</para></listitem> command on each file you changed.</para></listitem>
<listitem><para>Commit the change by using the <filename>git commit</filename> <listitem><para>Commit the change by using the <filename>git commit</filename>
command and push it to the "contrib" repository. 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> as described earlier.</para></listitem>
<listitem><para>Notify the maintainer that you have pushed a change by making a pull <listitem><para>Notify the maintainer that you have pushed a change by making a pull
request. request.
@ -1031,10 +1030,10 @@
You can find these scripts in the <filename>scripts</filename> directory of the You can find these scripts in the <filename>scripts</filename> directory of the
Yocto Project file structure.</para> Yocto Project file structure.</para>
<para>For help on using these scripts, simply provide the <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'> <literallayout class='monospaced'>
$ ~/poky/scripts/create-pull-request --help $ ~/poky/scripts/create-pull-request -h
$ ~/poky/scripts/send-pull-request --help $ ~/poky/scripts/send-pull-request -h
</literallayout></para></listitem> </literallayout></para></listitem>
</itemizedlist> </itemizedlist>
</para> </para>
@ -1054,8 +1053,8 @@
Here is a general procedure: Here is a general procedure:
<itemizedlist> <itemizedlist>
<listitem><para>Make your changes in your local Git repository.</para></listitem> <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> <listitem><para>Stage your changes by using the <filename>git add</filename>
command.</para></listitem> command on each file you changed.</para></listitem>
<listitem><para>Commit the change by using the <listitem><para>Commit the change by using the
<filename>git commit --signoff</filename> command. <filename>git commit --signoff</filename> command.
Using the <filename>--signoff</filename> option identifies you as the person Using the <filename>--signoff</filename> option identifies you as the person