| Message ID | 1467161456-23229-1-git-send-email-bill.fischofer@linaro.org |
|---|---|
| State | New |
| Headers | show |
On 28 June 2016 at 20:50, Bill Fischofer <bill.fischofer@linaro.org> wrote: > Signed-off-by: Bill Fischofer <bill.fischofer@linaro.org> > Reviewed-by: Mike Holmes <mike.holmes@linaro.org> > --- > v3: Spelling corrections + changes suggested by Christophe > > v2: Incorporate comments from Mike and Petri > > CONTRIBUTING | 162 > ++++++++++++++++++++++++++++++++++++++++++++++++++++++++--- > 1 file changed, 154 insertions(+), 8 deletions(-) > > diff --git a/CONTRIBUTING b/CONTRIBUTING > index a81fd8d..a49a34c 100644 > --- a/CONTRIBUTING > +++ b/CONTRIBUTING > @@ -11,15 +11,30 @@ in understanding the contributing requirements for ODP > This document is intended to guide a new application developer in > understanding > the contributing requirements for ODP > > +== Contributor's Agreement > +ODP is an open source project that follows the > +https://opensource.org/licenses/BSD-3-Clause[BSD 3 Clause] license. Every > +contributor to ODP must agree to comply by these licensing terms as well > as > +assert that they have the right to contribute the code they submit to the > +project. No patches will be considered for acceptance without the > contributor > +having first executed either an > +http://www.opendataplane.org/contributor/individual/[Individual > Contributor > +License Agreement] or being a member of an organization that has executed > +a http://www.opendataplane.org/contributor/corporate/[Corporate > Contributor > +License Agreement]. > + > +These agreements are a one-time requirement and take only a few minutes to > +perform by click-through. > + > == New Development > > ODP code shall be written with the kernel coding style > https://git.kernel.org/cgit/linux/kernel/git/torvalds/linux.git/tree/Documentation/CodingStyle[Kernel > Coding Style] > > ODP code shall be documented using the doxygen style described in the > -"Documenting the code" section. > +<<Documenting the Code>> section. > Check patch script/checkpatch.pl shall be used before submitting a patch. > > -== ODP patch expectations as an open source project > +== ODP patch expectations as an open source project > > While specific to the Linux kernel development, the following reference > could > also be considered a general guide for any Open Source development > @@ -42,14 +57,145 @@ which can be found in > https://git.kernel.org/cgit/linux/kernel/git/torvalds/linu > > Code without a proper signoff cannot be merged into the mainline. > > +== Short Log and Long Log Conventions > +For ease of patch management, every submitted patch must have a short log > +entry. The short log is a one-line summary of the patch and says where it > +is intended to be applied and (briefly) its purpose. Following the short > +log, submitters are free to add additional detail in the long log. Long > log > +entries are encouraged when appropriate. These should be relevant and > +useful to potential reviewers in understanding the purpose and rationale > +for the patch. See the above-referenced > + > https://git.kernel.org/cgit/linux/kernel/git/torvalds/linux.git/tree/Documentation/SubmittingPatches[Submitting > Patches] for some useful suggestions and > +guidelines. > + > +=== Short log format > +ODP requires that the short log be a single line not exceeding 80 > characters, > +be composed entirely in lower case, and be structured as follows: > + > +`area: component: brief description` > + > +Note that a single colon (:) should be used to separate each section of > the > +short log and be followed by a single space before beginning the next > section. > + > +Area identifies the functional area that this patch addresses and in > general > +says where in the directory hierarchy the patch is intended to apply. This > +should be taken from the following list: > + > +api:: > +Patch adds, deletes, or changes an ODP API. Any patch that applies to the > +`include/odp/api` directory or its descendants is considered an API patch > and > +must be identified as such. Moreover, any patch series containing an api > patch > +must be identified in the patch's `--subject-prefix` as API-NEXT. > + > +doc:: > +Patch applies to the ODP documentation library contained in the `doc` > directory > + > +drv:: > +Patch adds, deletes, or changes an ODP Driver specification. Any patch > that > +applies to the `include/odp/drv` directory or its descendants is > considered a > +DRV patch and must be identified as such. > + > +example:: > +Patch applies to the ODP examples contained in the `example` directory. > + > +helper:: > +Patch applies to the ODP helper library contained in the `helper` > directory. > + > +linux-generic:: > +linux-gen:: > +Patch applies to the odp-linux reference implementation, specifically the > +`platform/linux-generic/` directory that contains that implementation. The > +alternate form `linux-gen` may be used to conserve line space if desired. > + > +performance:: > +perftest:: > +Patch applies to the ODP performance test suite contained in the > +`test/performance` directory. > + > +test:: > +Patch applies to the `test` directory. This can be used as a generic area > +for non-specific test patches. > + > +validation:: > +Patch applies to the ODP validation test suite contained in the > +`test/validation` directory. > + > +Any other patch that applies to some other top-level directory or file > should > +use that directory or file name as its area. > + > +The component portion of the short log identifies the ODP component that > this > +patch applies to. A component is required unless the area is a single > file, in > +which case it may be omitted. Components should be selected from the > following > +list: > + > +buffer:: > +Buffers and buffer processing. > + > +classification:: > +cls:: > +Classification. `cls` may be used as an abbreviation for space if desired. > + > +crypto:: > +Crypto. > + > +packet:: > +Packets and packet processing. > + > +pktio:: > +Packet I/O (pktio) and its related sub-components > + > +pool:: > +Buffer pools and related processing. > + > +queue:: > +Queues and related processing. > + > +scheduler:: > +sched:: > +Scheduler and related processing. `sched` may be used as an abbreviation > for > +space if desired. > + > +time:: > +Time. > + > +timer:: > +Timers and related processing. > + > +tm:: > +Traffic Manager and related processing. > + > +Following the component the rest of the short log should describe the > purpose > +of this patch. > + > +=== Examples > +To illustrate, here are some examples of good and bad short logs: > + > +Good:: > +* `api: pool: add new foo attribute to pools` > +* `linux-generic: pool: implement new foo attribute for pools` > +* `validation: pool: test new foo attribute for pools` > + > +Bad:: > +* `fix something` (doesn't follow required format) > +* `api: propose a new api` (missing component) > +* `validation: pool: a description that rambles on and on and never gets > to > +the point` > + > == Common Errors in Patch and Commit Messages > > - Avoid starting the summary line with a capital letter, unless the > component > being referred to also begins with a capital letter. > -- Don't have one huge patch, split your change into logical subparts. It's > +- Don't have one huge patch, split your change into logical sub-parts. > It's > easier to track down problems afterward using tools such as git bisect. > It > also makes it easy for people to cherry-pick changes into things like > stable > - branches. > + branches. Note, however, that each part of a multi-part patch must > apply and > + build in sequence. That is, if the patch consists of three parts, Part > 1 must > + build by itself, as must Parts 1 and 2, in addition to all three parts > + together. > +- If a patch cannot be sepeated because of interdependencies (e.g., an > API is > + changed and this requires changes to the implementation of that API as > well > + as tests and examples that make use of it, then the short log should > reflect > + the "highest" level change made by the patch (in this case, API). > - Don't simply translate your change into English for a commit log. The > log > "Change compare from zero to one" is bad because it describes only the > code > change in the patch; we can see that from reading the patch itself. Let > the > @@ -79,7 +225,7 @@ Code without a proper signoff cannot be merged into the > mainline. > entry point, or start of the trace is relevant (i.e. a syscall or > similar), > you can leave that, and then replace a chunk of the intermediate calls > in the > middle with a single [...] > -- Don't include timestamps or other unnecessary information, unless they > are > +- Don't include time stamps or other unnecessary information, unless they > are > relevant to the situation (i.e. indicating an unacceptable delay in a > driver > initialization etc.) > - Don't use links to temporary resources like pastebin and friends. The > commit > @@ -90,9 +236,9 @@ Code without a proper signoff cannot be merged into the > mainline. > > == Documenting > > -- References to wikipedia are not permitted. > +- References to Wikipedia are not permitted. > > -=== Documenting the code > +=== Documenting the Code > > - Allow doxygen to use all its default behaviors to identify tagged > information but where a doxygen tag must be specified use @ > @@ -154,6 +300,6 @@ Code without a proper signoff cannot be merged into > the mainline. > image::../<image name>.svg[align="center"] > ---- > - The images are stored in the doc/images directory as svg files, src for > image > - generators such as .gv and .msg should also render to .svg > + generators such as .gv and .msc should also render to .svg > - Body text shall wrap at the 80 char point. > - No warnings may be generated by the asciidoctor tool. > -- > 2.7.4 > > _______________________________________________ > lng-odp mailing list > lng-odp@lists.linaro.org > https://lists.linaro.org/mailman/listinfo/lng-odp >
diff --git a/CONTRIBUTING b/CONTRIBUTING index a81fd8d..a49a34c 100644 --- a/CONTRIBUTING +++ b/CONTRIBUTING @@ -11,15 +11,30 @@ in understanding the contributing requirements for ODP This document is intended to guide a new application developer in understanding the contributing requirements for ODP +== Contributor's Agreement +ODP is an open source project that follows the +https://opensource.org/licenses/BSD-3-Clause[BSD 3 Clause] license. Every +contributor to ODP must agree to comply by these licensing terms as well as +assert that they have the right to contribute the code they submit to the +project. No patches will be considered for acceptance without the contributor +having first executed either an +http://www.opendataplane.org/contributor/individual/[Individual Contributor +License Agreement] or being a member of an organization that has executed +a http://www.opendataplane.org/contributor/corporate/[Corporate Contributor +License Agreement]. + +These agreements are a one-time requirement and take only a few minutes to +perform by click-through. + == New Development ODP code shall be written with the kernel coding style https://git.kernel.org/cgit/linux/kernel/git/torvalds/linux.git/tree/Documentation/CodingStyle[Kernel Coding Style] ODP code shall be documented using the doxygen style described in the -"Documenting the code" section. +<<Documenting the Code>> section. Check patch script/checkpatch.pl shall be used before submitting a patch. -== ODP patch expectations as an open source project +== ODP patch expectations as an open source project While specific to the Linux kernel development, the following reference could also be considered a general guide for any Open Source development @@ -42,14 +57,145 @@ which can be found in https://git.kernel.org/cgit/linux/kernel/git/torvalds/linu Code without a proper signoff cannot be merged into the mainline. +== Short Log and Long Log Conventions +For ease of patch management, every submitted patch must have a short log +entry. The short log is a one-line summary of the patch and says where it +is intended to be applied and (briefly) its purpose. Following the short +log, submitters are free to add additional detail in the long log. Long log +entries are encouraged when appropriate. These should be relevant and +useful to potential reviewers in understanding the purpose and rationale +for the patch. See the above-referenced +https://git.kernel.org/cgit/linux/kernel/git/torvalds/linux.git/tree/Documentation/SubmittingPatches[Submitting Patches] for some useful suggestions and +guidelines. + +=== Short log format +ODP requires that the short log be a single line not exceeding 80 characters, +be composed entirely in lower case, and be structured as follows: + +`area: component: brief description` + +Note that a single colon (:) should be used to separate each section of the +short log and be followed by a single space before beginning the next section. + +Area identifies the functional area that this patch addresses and in general +says where in the directory hierarchy the patch is intended to apply. This +should be taken from the following list: + +api:: +Patch adds, deletes, or changes an ODP API. Any patch that applies to the +`include/odp/api` directory or its descendants is considered an API patch and +must be identified as such. Moreover, any patch series containing an api patch +must be identified in the patch's `--subject-prefix` as API-NEXT. + +doc:: +Patch applies to the ODP documentation library contained in the `doc` directory + +drv:: +Patch adds, deletes, or changes an ODP Driver specification. Any patch that +applies to the `include/odp/drv` directory or its descendants is considered a +DRV patch and must be identified as such. + +example:: +Patch applies to the ODP examples contained in the `example` directory. + +helper:: +Patch applies to the ODP helper library contained in the `helper` directory. + +linux-generic:: +linux-gen:: +Patch applies to the odp-linux reference implementation, specifically the +`platform/linux-generic/` directory that contains that implementation. The +alternate form `linux-gen` may be used to conserve line space if desired. + +performance:: +perftest:: +Patch applies to the ODP performance test suite contained in the +`test/performance` directory. + +test:: +Patch applies to the `test` directory. This can be used as a generic area +for non-specific test patches. + +validation:: +Patch applies to the ODP validation test suite contained in the +`test/validation` directory. + +Any other patch that applies to some other top-level directory or file should +use that directory or file name as its area. + +The component portion of the short log identifies the ODP component that this +patch applies to. A component is required unless the area is a single file, in +which case it may be omitted. Components should be selected from the following +list: + +buffer:: +Buffers and buffer processing. + +classification:: +cls:: +Classification. `cls` may be used as an abbreviation for space if desired. + +crypto:: +Crypto. + +packet:: +Packets and packet processing. + +pktio:: +Packet I/O (pktio) and its related sub-components + +pool:: +Buffer pools and related processing. + +queue:: +Queues and related processing. + +scheduler:: +sched:: +Scheduler and related processing. `sched` may be used as an abbreviation for +space if desired. + +time:: +Time. + +timer:: +Timers and related processing. + +tm:: +Traffic Manager and related processing. + +Following the component the rest of the short log should describe the purpose +of this patch. + +=== Examples +To illustrate, here are some examples of good and bad short logs: + +Good:: +* `api: pool: add new foo attribute to pools` +* `linux-generic: pool: implement new foo attribute for pools` +* `validation: pool: test new foo attribute for pools` + +Bad:: +* `fix something` (doesn't follow required format) +* `api: propose a new api` (missing component) +* `validation: pool: a description that rambles on and on and never gets to +the point` + == Common Errors in Patch and Commit Messages - Avoid starting the summary line with a capital letter, unless the component being referred to also begins with a capital letter. -- Don't have one huge patch, split your change into logical subparts. It's +- Don't have one huge patch, split your change into logical sub-parts. It's easier to track down problems afterward using tools such as git bisect. It also makes it easy for people to cherry-pick changes into things like stable - branches. + branches. Note, however, that each part of a multi-part patch must apply and + build in sequence. That is, if the patch consists of three parts, Part 1 must + build by itself, as must Parts 1 and 2, in addition to all three parts + together. +- If a patch cannot be sepeated because of interdependencies (e.g., an API is + changed and this requires changes to the implementation of that API as well + as tests and examples that make use of it, then the short log should reflect + the "highest" level change made by the patch (in this case, API). - Don't simply translate your change into English for a commit log. The log "Change compare from zero to one" is bad because it describes only the code change in the patch; we can see that from reading the patch itself. Let the @@ -79,7 +225,7 @@ Code without a proper signoff cannot be merged into the mainline. entry point, or start of the trace is relevant (i.e. a syscall or similar), you can leave that, and then replace a chunk of the intermediate calls in the middle with a single [...] -- Don't include timestamps or other unnecessary information, unless they are +- Don't include time stamps or other unnecessary information, unless they are relevant to the situation (i.e. indicating an unacceptable delay in a driver initialization etc.) - Don't use links to temporary resources like pastebin and friends. The commit @@ -90,9 +236,9 @@ Code without a proper signoff cannot be merged into the mainline. == Documenting -- References to wikipedia are not permitted. +- References to Wikipedia are not permitted. -=== Documenting the code +=== Documenting the Code - Allow doxygen to use all its default behaviors to identify tagged information but where a doxygen tag must be specified use @ @@ -154,6 +300,6 @@ Code without a proper signoff cannot be merged into the mainline. image::../<image name>.svg[align="center"] ---- - The images are stored in the doc/images directory as svg files, src for image - generators such as .gv and .msg should also render to .svg + generators such as .gv and .msc should also render to .svg - Body text shall wrap at the 80 char point. - No warnings may be generated by the asciidoctor tool.
Signed-off-by: Bill Fischofer <bill.fischofer@linaro.org> --- v3: Spelling corrections + changes suggested by Christophe v2: Incorporate comments from Mike and Petri CONTRIBUTING | 162 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 154 insertions(+), 8 deletions(-)