[PATCHv2,ARCH] Add contributing instructions to the Arch document

Signed-off-by: Mike Holmes <mike.holmes@linaro.org>
---
 CONTRIBUTING     | 46 ++++++++++++++++++++++++++++++++++++++++++++++
 Doxyfile.in      |  1 +
 contributing.dox | 12 ++++++++++++
 3 files changed, 59 insertions(+)
 create mode 100644 CONTRIBUTING
 create mode 100644 contributing.dox

On Tue, Jul 15, 2014 at 1:15 PM, Mike Holmes <mike.holmes@linaro.org> wrote:

>
> +++ b/CONTRIBUTING
> @@ -0,0 +1,46 @@
> +  Contributing to the OpenDataPlane (ODP) API Architecture
> +
> +  Changes or additions should be a patch to this repository and should be
> +sent to "lng-odp@lists.linaro.org" with the subject containing PATCH and
> ARCH,
> +this can be archived with the following if it were the 4th version of the
> patch
> +  'git format-patch  --subject-prefix="PATCHv4 ARCH"'
>

This recommendation conflicts with the existing README, which says, in part:

Mailing list:
    lng-odp@lists.linaro.org
Please read CONTRIBUTING file before submitting patches.
Email prefixes:
  [PATCH] means patch is for odp.git;
[APPS/PATCH] means patch is for odp-apps.git
[ARCH/PATCH] means patch is for odp-architecture.git;

So we should be consistent between these two.

Bill

Interesting,  should the API repo list information for the ARCH doc and
application repos in that way?  I dont think it should other than to
acknowledge they exist, if nothing else the contributing text is different
with different rules on what is acceptable, different build mechanism etc.

Then there is the content of the API repo readme specifically, as you point
out I think it needs updating because the format in use on the list does
not match for syntax described there I have not seen backslashes used on
common lists.

I think the API repo readme should be fixed and each repo left to define
its own rules.

I.e. delete
[APPS/PATCH] means patch is for odp-apps.git
[ARCH/PATCH] means patch is for odp-architecture.git;

Mike


On 15 July 2014 15:33, Bill Fischofer <bill.fischofer@linaro.org> wrote:

> On Tue, Jul 15, 2014 at 1:15 PM, Mike Holmes <mike.holmes@linaro.org>
> wrote:
>
>>
>> +++ b/CONTRIBUTING
>> @@ -0,0 +1,46 @@
>> +  Contributing to the OpenDataPlane (ODP) API Architecture
>> +
>> +  Changes or additions should be a patch to this repository and should be
>> +sent to "lng-odp@lists.linaro.org" with the subject containing PATCH
>> and ARCH,
>> +this can be archived with the following if it were the 4th version of
>> the patch
>> +  'git format-patch  --subject-prefix="PATCHv4 ARCH"'
>>
>
> This recommendation conflicts with the existing README, which says, in
> part:
>
> Mailing list:
>     lng-odp@lists.linaro.org
> Please read CONTRIBUTING file before submitting patches.
> Email prefixes:
>    [PATCH] means patch is for odp.git;
> [APPS/PATCH] means patch is for odp-apps.git
> [ARCH/PATCH] means patch is for odp-architecture.git;
>
> So we should be consistent between these two.
>
> Bill
>

On 2014-07-15 16:00, Mike Holmes wrote:
> Interesting,  should the API repo list information for the ARCH doc and
> application repos in that way?  I dont think it should other than to
> acknowledge they exist, if nothing else the contributing text is different
> with different rules on what is acceptable, different build mechanism etc.
> 
> Then there is the content of the API repo readme specifically, as you point
> out I think it needs updating because the format in use on the list does
> not match for syntax described there I have not seen backslashes used on
> common lists.
> 
> I think the API repo readme should be fixed and each repo left to define
> its own rules.

I agree with you here.

What do you say Bill?
Are you fine with accepting this patch?

> 
> I.e. delete
> [APPS/PATCH] means patch is for odp-apps.git
> [ARCH/PATCH] means patch is for odp-architecture.git;

I already sent a patch to odp for this.

Cheers,
Anders

> 
> Mike
> 
> 
> On 15 July 2014 15:33, Bill Fischofer <bill.fischofer@linaro.org> wrote:
> 
> > On Tue, Jul 15, 2014 at 1:15 PM, Mike Holmes <mike.holmes@linaro.org>
> > wrote:
> >
> >>
> >> +++ b/CONTRIBUTING
> >> @@ -0,0 +1,46 @@
> >> +  Contributing to the OpenDataPlane (ODP) API Architecture
> >> +
> >> +  Changes or additions should be a patch to this repository and should be
> >> +sent to "lng-odp@lists.linaro.org" with the subject containing PATCH
> >> and ARCH,
> >> +this can be archived with the following if it were the 4th version of
> >> the patch
> >> +  'git format-patch  --subject-prefix="PATCHv4 ARCH"'
> >>
> >
> > This recommendation conflicts with the existing README, which says, in
> > part:
> >
> > Mailing list:
> >     lng-odp@lists.linaro.org
> > Please read CONTRIBUTING file before submitting patches.
> > Email prefixes:
> >    [PATCH] means patch is for odp.git;
> > [APPS/PATCH] means patch is for odp-apps.git
> > [ARCH/PATCH] means patch is for odp-architecture.git;
> >
> > So we should be consistent between these two.
> >
> > Bill
> >
> 
> 
> 
> -- 
> *Mike Holmes*
> Linaro Technical Manager / Lead
> LNG - ODP

> _______________________________________________
> lng-odp mailing list
> lng-odp@lists.linaro.org
> http://lists.linaro.org/mailman/listinfo/lng-odp

On 07/15/2014 10:15 PM, Mike Holmes wrote:
> Signed-off-by: Mike Holmes <mike.holmes@linaro.org>
> ---
>   CONTRIBUTING     | 46 ++++++++++++++++++++++++++++++++++++++++++++++
>   Doxyfile.in      |  1 +
>   contributing.dox | 12 ++++++++++++
>   3 files changed, 59 insertions(+)
>   create mode 100644 CONTRIBUTING
>   create mode 100644 contributing.dox
>
> diff --git a/CONTRIBUTING b/CONTRIBUTING
> new file mode 100644
> index 0000000..3b985d4
> --- /dev/null
> +++ b/CONTRIBUTING
> @@ -0,0 +1,46 @@
> +  Contributing to the OpenDataPlane (ODP) API Architecture
> +
> +  Changes or additions should be a patch to this repository and should be
> +sent to "lng-odp@lists.linaro.org" with the subject containing PATCH and ARCH,
> +this can be archived with the following if it were the 4th version of the patch
> +  'git format-patch  --subject-prefix="PATCHv4 ARCH"'

--find-renames

> +
> +    To certify you wrote the text, or otherwise have the right to pass it
> +on (presumably from a compatibly licensed project), we use the "Developer's
> +Certificate of Origin" (see [1]).  Using this sign-off process, we are able to
> +keep track of compliance to our license (see LICENSE file).
> +
> +  There must be no trailing whitespace, space before tabs or trailing newlines
> +"git am <patch-name>" will high light these issues, vi, emacs etc all have
> +tools to clean this up automatically
> +
> +  No additional manual flow formatting should be included, for example
> +adding "\n\n" add spaces, generally indicates that it would be better to use
> +lists, modules, pages or sections and subsections are really what is required.
> +
> +  Doxygen will concatenate sentences placed on consecutive lines so that they
> +flow as a single paragraph, this allows git to see changes on a per sentence
> +level which much clearer diff results between revisions.
> +
> +  Thus the text should be structured like this:
> +
> +  "This is a sentence.
> +  And this is another one."
> +
> +  and not like this:
> +
> +  "This is a sentence. And this is another one."
> +
> +  The "@" symbol should be used to mark Doxygen special commands
> +
> +  Images are stored in the images directory in png format and must have a png and eps version
> +so that they render correctly for the html and pdf documents. For example
> +an image called syncmodels will be found in the images directory
> +as syncmodels.png & syncmodels.eps. The correct reference to these images is
> +then provided with:
> +
> +@image html syncmodels.png "Figure 1: Synchronization Models"
> +@image latex syncmodels.eps "Figure 1: Synchronization Models" width=\textwidth
> +
> +
> +[1] https://git.kernel.org/cgit/linux/kernel/git/torvalds/linux.git/tree/Documentation/SubmittingPatches
> diff --git a/Doxyfile.in b/Doxyfile.in
> index d8aec46..728474e 100644
> --- a/Doxyfile.in
> +++ b/Doxyfile.in
> @@ -13,3 +13,4 @@ PROJECT_LOGO = images/ODP-Logo-HQ.png
>   IMAGE_PATH = images
>   INPUT = .
>   FULL_PATH_NAMES = NO
> +EXAMPLE_PATH = .
> diff --git a/contributing.dox b/contributing.dox
> new file mode 100644
> index 0000000..a6e28fd
> --- /dev/null
> +++ b/contributing.dox
> @@ -0,0 +1,12 @@
> +/* Copyright (c) 2013, Linaro Limited
> + * All rights reserved
> + *
> + * SPDX-License-Identifier:     BSD-3-Clause
> + */
> +
> +/**
> +@page  Contributing
> +
> +@verbinclude CONTRIBUTING
> +
> +*/

I have no problem with these changes.  We should just be consistent in what
we tell people in the different files in the repository to avoid confusion.

Bill


On Thu, Jul 17, 2014 at 5:54 AM, Maxim Uvarov <maxim.uvarov@linaro.org>
wrote:

> On 07/15/2014 10:15 PM, Mike Holmes wrote:
>
>> Signed-off-by: Mike Holmes <mike.holmes@linaro.org>
>> ---
>>   CONTRIBUTING     | 46 ++++++++++++++++++++++++++++++++++++++++++++++
>>   Doxyfile.in      |  1 +
>>   contributing.dox | 12 ++++++++++++
>>   3 files changed, 59 insertions(+)
>>   create mode 100644 CONTRIBUTING
>>   create mode 100644 contributing.dox
>>
>> diff --git a/CONTRIBUTING b/CONTRIBUTING
>> new file mode 100644
>> index 0000000..3b985d4
>> --- /dev/null
>> +++ b/CONTRIBUTING
>> @@ -0,0 +1,46 @@
>> +  Contributing to the OpenDataPlane (ODP) API Architecture
>> +
>> +  Changes or additions should be a patch to this repository and should be
>> +sent to "lng-odp@lists.linaro.org" with the subject containing PATCH
>> and ARCH,
>> +this can be archived with the following if it were the 4th version of
>> the patch
>> +  'git format-patch  --subject-prefix="PATCHv4 ARCH"'
>>
>
> --find-renames
>
>
>  +
>> +    To certify you wrote the text, or otherwise have the right to pass it
>> +on (presumably from a compatibly licensed project), we use the
>> "Developer's
>> +Certificate of Origin" (see [1]).  Using this sign-off process, we are
>> able to
>> +keep track of compliance to our license (see LICENSE file).
>> +
>> +  There must be no trailing whitespace, space before tabs or trailing
>> newlines
>> +"git am <patch-name>" will high light these issues, vi, emacs etc all
>> have
>> +tools to clean this up automatically
>> +
>> +  No additional manual flow formatting should be included, for example
>> +adding "\n\n" add spaces, generally indicates that it would be better to
>> use
>> +lists, modules, pages or sections and subsections are really what is
>> required.
>> +
>> +  Doxygen will concatenate sentences placed on consecutive lines so that
>> they
>> +flow as a single paragraph, this allows git to see changes on a per
>> sentence
>> +level which much clearer diff results between revisions.
>> +
>> +  Thus the text should be structured like this:
>> +
>> +  "This is a sentence.
>> +  And this is another one."
>> +
>> +  and not like this:
>> +
>> +  "This is a sentence. And this is another one."
>> +
>> +  The "@" symbol should be used to mark Doxygen special commands
>> +
>> +  Images are stored in the images directory in png format and must have
>> a png and eps version
>> +so that they render correctly for the html and pdf documents. For example
>> +an image called syncmodels will be found in the images directory
>> +as syncmodels.png & syncmodels.eps. The correct reference to these
>> images is
>> +then provided with:
>> +
>> +@image html syncmodels.png "Figure 1: Synchronization Models"
>> +@image latex syncmodels.eps "Figure 1: Synchronization Models"
>> width=\textwidth
>> +
>> +
>> +[1] https://git.kernel.org/cgit/linux/kernel/git/torvalds/
>> linux.git/tree/Documentation/SubmittingPatches
>> diff --git a/Doxyfile.in b/Doxyfile.in
>> index d8aec46..728474e 100644
>> --- a/Doxyfile.in
>> +++ b/Doxyfile.in
>> @@ -13,3 +13,4 @@ PROJECT_LOGO = images/ODP-Logo-HQ.png
>>   IMAGE_PATH = images
>>   INPUT = .
>>   FULL_PATH_NAMES = NO
>> +EXAMPLE_PATH = .
>> diff --git a/contributing.dox b/contributing.dox
>> new file mode 100644
>> index 0000000..a6e28fd
>> --- /dev/null
>> +++ b/contributing.dox
>> @@ -0,0 +1,12 @@
>> +/* Copyright (c) 2013, Linaro Limited
>> + * All rights reserved
>> + *
>> + * SPDX-License-Identifier:     BSD-3-Clause
>> + */
>> +
>> +/**
>> +@page  Contributing
>> +
>> +@verbinclude CONTRIBUTING
>> +
>> +*/
>>
>
>
> _______________________________________________
> lng-odp mailing list
> lng-odp@lists.linaro.org
> http://lists.linaro.org/mailman/listinfo/lng-odp
>

On 2014-07-17 06:22, Bill Fischofer wrote:
> I have no problem with these changes.  We should just be consistent in what
> we tell people in the different files in the repository to avoid confusion.

Mike, will you rework this patch and resubmit it?

Cheers,
Anders

> 
> Bill
> 
> 
> On Thu, Jul 17, 2014 at 5:54 AM, Maxim Uvarov <maxim.uvarov@linaro.org>
> wrote:
> 
> > On 07/15/2014 10:15 PM, Mike Holmes wrote:
> >
> >> Signed-off-by: Mike Holmes <mike.holmes@linaro.org>
> >> ---
> >>   CONTRIBUTING     | 46 ++++++++++++++++++++++++++++++++++++++++++++++
> >>   Doxyfile.in      |  1 +
> >>   contributing.dox | 12 ++++++++++++
> >>   3 files changed, 59 insertions(+)
> >>   create mode 100644 CONTRIBUTING
> >>   create mode 100644 contributing.dox
> >>
> >> diff --git a/CONTRIBUTING b/CONTRIBUTING
> >> new file mode 100644
> >> index 0000000..3b985d4
> >> --- /dev/null
> >> +++ b/CONTRIBUTING
> >> @@ -0,0 +1,46 @@
> >> +  Contributing to the OpenDataPlane (ODP) API Architecture
> >> +
> >> +  Changes or additions should be a patch to this repository and should be
> >> +sent to "lng-odp@lists.linaro.org" with the subject containing PATCH
> >> and ARCH,
> >> +this can be archived with the following if it were the 4th version of
> >> the patch
> >> +  'git format-patch  --subject-prefix="PATCHv4 ARCH"'
> >>
> >
> > --find-renames
> >
> >
> >  +
> >> +    To certify you wrote the text, or otherwise have the right to pass it
> >> +on (presumably from a compatibly licensed project), we use the
> >> "Developer's
> >> +Certificate of Origin" (see [1]).  Using this sign-off process, we are
> >> able to
> >> +keep track of compliance to our license (see LICENSE file).
> >> +
> >> +  There must be no trailing whitespace, space before tabs or trailing
> >> newlines
> >> +"git am <patch-name>" will high light these issues, vi, emacs etc all
> >> have
> >> +tools to clean this up automatically
> >> +
> >> +  No additional manual flow formatting should be included, for example
> >> +adding "\n\n" add spaces, generally indicates that it would be better to
> >> use
> >> +lists, modules, pages or sections and subsections are really what is
> >> required.
> >> +
> >> +  Doxygen will concatenate sentences placed on consecutive lines so that
> >> they
> >> +flow as a single paragraph, this allows git to see changes on a per
> >> sentence
> >> +level which much clearer diff results between revisions.
> >> +
> >> +  Thus the text should be structured like this:
> >> +
> >> +  "This is a sentence.
> >> +  And this is another one."
> >> +
> >> +  and not like this:
> >> +
> >> +  "This is a sentence. And this is another one."
> >> +
> >> +  The "@" symbol should be used to mark Doxygen special commands
> >> +
> >> +  Images are stored in the images directory in png format and must have
> >> a png and eps version
> >> +so that they render correctly for the html and pdf documents. For example
> >> +an image called syncmodels will be found in the images directory
> >> +as syncmodels.png & syncmodels.eps. The correct reference to these
> >> images is
> >> +then provided with:
> >> +
> >> +@image html syncmodels.png "Figure 1: Synchronization Models"
> >> +@image latex syncmodels.eps "Figure 1: Synchronization Models"
> >> width=\textwidth
> >> +
> >> +
> >> +[1] https://git.kernel.org/cgit/linux/kernel/git/torvalds/
> >> linux.git/tree/Documentation/SubmittingPatches
> >> diff --git a/Doxyfile.in b/Doxyfile.in
> >> index d8aec46..728474e 100644
> >> --- a/Doxyfile.in
> >> +++ b/Doxyfile.in
> >> @@ -13,3 +13,4 @@ PROJECT_LOGO = images/ODP-Logo-HQ.png
> >>   IMAGE_PATH = images
> >>   INPUT = .
> >>   FULL_PATH_NAMES = NO
> >> +EXAMPLE_PATH = .
> >> diff --git a/contributing.dox b/contributing.dox
> >> new file mode 100644
> >> index 0000000..a6e28fd
> >> --- /dev/null
> >> +++ b/contributing.dox
> >> @@ -0,0 +1,12 @@
> >> +/* Copyright (c) 2013, Linaro Limited
> >> + * All rights reserved
> >> + *
> >> + * SPDX-License-Identifier:     BSD-3-Clause
> >> + */
> >> +
> >> +/**
> >> +@page  Contributing
> >> +
> >> +@verbinclude CONTRIBUTING
> >> +
> >> +*/
> >>
> >
> >
> > _______________________________________________
> > lng-odp mailing list
> > lng-odp@lists.linaro.org
> > http://lists.linaro.org/mailman/listinfo/lng-odp
> >

> _______________________________________________
> lng-odp mailing list
> lng-odp@lists.linaro.org
> http://lists.linaro.org/mailman/listinfo/lng-odp

Yes, I will resubmit,  on vacation today


On 25 July 2014 11:01, Anders Roxell <anders.roxell@linaro.org> wrote:

> On 2014-07-17 06:22, Bill Fischofer wrote:
> > I have no problem with these changes.  We should just be consistent in
> what
> > we tell people in the different files in the repository to avoid
> confusion.
>
> Mike, will you rework this patch and resubmit it?
>
> Cheers,
> Anders
>
> >
> > Bill
> >
> >
> > On Thu, Jul 17, 2014 at 5:54 AM, Maxim Uvarov <maxim.uvarov@linaro.org>
> > wrote:
> >
> > > On 07/15/2014 10:15 PM, Mike Holmes wrote:
> > >
> > >> Signed-off-by: Mike Holmes <mike.holmes@linaro.org>
> > >> ---
> > >>   CONTRIBUTING     | 46 ++++++++++++++++++++++++++++++++++++++++++++++
> > >>   Doxyfile.in      |  1 +
> > >>   contributing.dox | 12 ++++++++++++
> > >>   3 files changed, 59 insertions(+)
> > >>   create mode 100644 CONTRIBUTING
> > >>   create mode 100644 contributing.dox
> > >>
> > >> diff --git a/CONTRIBUTING b/CONTRIBUTING
> > >> new file mode 100644
> > >> index 0000000..3b985d4
> > >> --- /dev/null
> > >> +++ b/CONTRIBUTING
> > >> @@ -0,0 +1,46 @@
> > >> +  Contributing to the OpenDataPlane (ODP) API Architecture
> > >> +
> > >> +  Changes or additions should be a patch to this repository and
> should be
> > >> +sent to "lng-odp@lists.linaro.org" with the subject containing PATCH
> > >> and ARCH,
> > >> +this can be archived with the following if it were the 4th version of
> > >> the patch
> > >> +  'git format-patch  --subject-prefix="PATCHv4 ARCH"'
> > >>
> > >
> > > --find-renames
> > >
> > >
> > >  +
> > >> +    To certify you wrote the text, or otherwise have the right to
> pass it
> > >> +on (presumably from a compatibly licensed project), we use the
> > >> "Developer's
> > >> +Certificate of Origin" (see [1]).  Using this sign-off process, we
> are
> > >> able to
> > >> +keep track of compliance to our license (see LICENSE file).
> > >> +
> > >> +  There must be no trailing whitespace, space before tabs or trailing
> > >> newlines
> > >> +"git am <patch-name>" will high light these issues, vi, emacs etc all
> > >> have
> > >> +tools to clean this up automatically
> > >> +
> > >> +  No additional manual flow formatting should be included, for
> example
> > >> +adding "\n\n" add spaces, generally indicates that it would be
> better to
> > >> use
> > >> +lists, modules, pages or sections and subsections are really what is
> > >> required.
> > >> +
> > >> +  Doxygen will concatenate sentences placed on consecutive lines so
> that
> > >> they
> > >> +flow as a single paragraph, this allows git to see changes on a per
> > >> sentence
> > >> +level which much clearer diff results between revisions.
> > >> +
> > >> +  Thus the text should be structured like this:
> > >> +
> > >> +  "This is a sentence.
> > >> +  And this is another one."
> > >> +
> > >> +  and not like this:
> > >> +
> > >> +  "This is a sentence. And this is another one."
> > >> +
> > >> +  The "@" symbol should be used to mark Doxygen special commands
> > >> +
> > >> +  Images are stored in the images directory in png format and must
> have
> > >> a png and eps version
> > >> +so that they render correctly for the html and pdf documents. For
> example
> > >> +an image called syncmodels will be found in the images directory
> > >> +as syncmodels.png & syncmodels.eps. The correct reference to these
> > >> images is
> > >> +then provided with:
> > >> +
> > >> +@image html syncmodels.png "Figure 1: Synchronization Models"
> > >> +@image latex syncmodels.eps "Figure 1: Synchronization Models"
> > >> width=\textwidth
> > >> +
> > >> +
> > >> +[1] https://git.kernel.org/cgit/linux/kernel/git/torvalds/
> > >> linux.git/tree/Documentation/SubmittingPatches
> > >> diff --git a/Doxyfile.in b/Doxyfile.in
> > >> index d8aec46..728474e 100644
> > >> --- a/Doxyfile.in
> > >> +++ b/Doxyfile.in
> > >> @@ -13,3 +13,4 @@ PROJECT_LOGO = images/ODP-Logo-HQ.png
> > >>   IMAGE_PATH = images
> > >>   INPUT = .
> > >>   FULL_PATH_NAMES = NO
> > >> +EXAMPLE_PATH = .
> > >> diff --git a/contributing.dox b/contributing.dox
> > >> new file mode 100644
> > >> index 0000000..a6e28fd
> > >> --- /dev/null
> > >> +++ b/contributing.dox
> > >> @@ -0,0 +1,12 @@
> > >> +/* Copyright (c) 2013, Linaro Limited
> > >> + * All rights reserved
> > >> + *
> > >> + * SPDX-License-Identifier:     BSD-3-Clause
> > >> + */
> > >> +
> > >> +/**
> > >> +@page  Contributing
> > >> +
> > >> +@verbinclude CONTRIBUTING
> > >> +
> > >> +*/
> > >>
> > >
> > >
> > > _______________________________________________
> > > lng-odp mailing list
> > > lng-odp@lists.linaro.org
> > > http://lists.linaro.org/mailman/listinfo/lng-odp
> > >
>
> > _______________________________________________
> > lng-odp mailing list
> > lng-odp@lists.linaro.org
> > http://lists.linaro.org/mailman/listinfo/lng-odp
>
>
> --
> Anders Roxell
> anders.roxell@linaro.org
> M: +46 709 71 42 85 | IRC: roxell
>
> _______________________________________________
> lng-odp mailing list
> lng-odp@lists.linaro.org
> http://lists.linaro.org/mailman/listinfo/lng-odp
>