From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mga09.intel.com (mga09.intel.com [134.134.136.24]) by yocto-www.yoctoproject.org (Postfix) with ESMTP id CA91CE01443 for ; Mon, 2 Jul 2012 08:57:02 -0700 (PDT) Received: from orsmga001.jf.intel.com ([10.7.209.18]) by orsmga102.jf.intel.com with ESMTP; 02 Jul 2012 08:57:02 -0700 X-ExtLoop1: 1 X-IronPort-AV: E=Sophos;i="4.67,352,1309762800"; d="scan'208";a="160581368" Received: from btwarden-mobl1.amr.corp.intel.com (HELO envy.home) ([10.7.199.162]) by orsmga001.jf.intel.com with ESMTP; 02 Jul 2012 08:57:02 -0700 Message-ID: <4FF1C475.9090502@linux.intel.com> Date: Mon, 02 Jul 2012 08:55:33 -0700 From: Darren Hart User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:13.0) Gecko/20120615 Thunderbird/13.0.1 MIME-Version: 1.0 To: Paul Eggleton References: <140b0d7e96a6b852346e415b91d26f1d41ac88ea.1341222778.git.paul.eggleton@linux.intel.com> In-Reply-To: <140b0d7e96a6b852346e415b91d26f1d41ac88ea.1341222778.git.paul.eggleton@linux.intel.com> X-Enigmail-Version: 1.4.2 Cc: yocto@yoctoproject.org Subject: Re: [yocto-docs] [PATCH 2/5] dev-manual: tidy up "How to Submit a Change" section X-BeenThere: yocto@yoctoproject.org X-Mailman-Version: 2.1.13 Precedence: list List-Id: Discussion of all things Yocto List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Mon, 02 Jul 2012 15:57:03 -0000 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit On 07/02/2012 02:54 AM, Paul Eggleton wrote: > * 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 That fixes Bug 2671, consider adding the tag to the commit header. [YOCTO #2671] > * Clarify commit message guidelines > * Touch up a few other bits and pieces > > Signed-off-by: Paul Eggleton > --- > documentation/dev-manual/dev-manual-newbie.xml | 119 ++++++++++++------------ > 1 file changed, 59 insertions(+), 60 deletions(-) > > diff --git a/documentation/dev-manual/dev-manual-newbie.xml b/documentation/dev-manual/dev-manual-newbie.xml > index 6a8d39c..4a39a59 100644 > --- a/documentation/dev-manual/dev-manual-newbie.xml > +++ b/documentation/dev-manual/dev-manual-newbie.xml > @@ -855,54 +855,53 @@ > Submit the bug by clicking the "Submit Bug" button. > > > - > - > - Bugs in the Yocto Project Bugzilla follow naming convention: > - [YOCTO #<number>], where <number> is the > - assigned defect ID used in Bugzilla. > - So, for example, a valid way to refer to a defect would be [YOCTO #1011]. > - This convention becomes important if you are submitting patches against the Yocto Project > - code itself. > - > > >
> How to Submit a Change > > > - 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 > "Mailing lists" section in > The Yocto Project Reference Manual. > > > > - 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: > > - For defects against the Yocto Project build system Poky, send > - your patch to the > - 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 meta layer > - or the BitBake Manual could be sent to this mailing list. > - For defects against Yocto-specific layers, tools, and Yocto Project > - documentation use the > - mailing list. > - This mailing list corresponds to Yocto-specific areas such as > - meta-yocto, meta-intel, > - linux-yocto, and documentation. > + 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 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: > > Developer's Certificate of Origin 1.1 > @@ -931,52 +930,52 @@ > maintained indefinitely and may be redistributed consistent with > this project or the open source license(s) involved. > > - A Poky contributions tree (poky-contrib, > - git://git.yoctoproject.org/poky-contrib.git) > - 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. > > > > 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. > > > > - 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: > > 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. > > 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. > > 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: > > - YOCTO #<bug-id>: <Detailed description of commit> > + <detailed description of change> > + > + [YOCTO #<bug-id>] > > + Where <bug-id> is replaced with the specific bug ID from the > + Yocto Project Bugzilla instance. > > > > @@ -997,11 +996,11 @@ > The basic flow for pushing a change to an upstream "contrib" Git repository is as follows: > > Make your changes in your local Git repository. > - Stage your commit (or change) by using the git add > - command. > + Stage your changes by using the git add > + command on each file you changed. > Commit the change by using the git commit > 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. > Notify the maintainer that you have pushed a change by making a pull > request. > @@ -1012,10 +1011,10 @@ > You can find these scripts in the scripts directory of the > Yocto Project file structure. > For help on using these scripts, simply provide the > - --help argument as follows: > + -h argument as follows: > > - $ ~/poky/scripts/create-pull-request --help > - $ ~/poky/scripts/send-pull-request --help > + $ ~/poky/scripts/create-pull-request -h > + $ ~/poky/scripts/send-pull-request -h > > > > @@ -1035,8 +1034,8 @@ > Here is a general procedure: > > Make your changes in your local Git repository. > - Stage your commit (or change) by using the git add > - command. > + Stage your changes by using the git add > + command on each file you changed. > Commit the change by using the > git commit --signoff command. > Using the --signoff option identifies you as the person > -- Darren Hart Intel Open Source Technology Center Yocto Project - Linux Kernel