[Buildroot] [PATCH v2 1/1] manual: update review process and patchwork

[Buildroot] [PATCH v2 1/1] manual: update review process and patchwork

[Ryan Barnett]

Adding more documentaiton based on discussion from the mailing list
in regards the buildroot review process and how patchworks can be
used to pull in patches for testing purposes.

Mailing list discussion:
http://lists.busybox.net/pipermail/buildroot/2013-September/078170.html

Signed-off-by: Ryan Barnett <rjbarnet@rockwellcollins.com>

---

v1 -> v2
 * Updated all references to patchwork to be Patchwork or Buildroot's
   Patchwork instead of a few misspellings (suggested by Thomas
   Petazzoni)
 * Added clarification that patchwork main use is for the Buildroot
   maintainer (suggested by Thomas Petazzoni)

Signed-off-by: Ryan Barnett <rjbarnet@rockwellcollins.com>
---
 docs/manual/contribute.txt   |   12 +++++++++++-
 docs/manual/get-involved.txt |   38 +++++++++++++++++++++++++++++++++++---
 2 files changed, 46 insertions(+), 4 deletions(-)

diff --git a/docs/manual/contribute.txt b/docs/manual/contribute.txt
index 2b2783d..201685c 100644
--- a/docs/manual/contribute.txt
+++ b/docs/manual/contribute.txt
@@ -132,9 +132,15 @@ $ git format-patch --subject-prefix "PATCH v4" \
 Reviewing/Testing patches
 -------------------------
 
+The review process for new patches is done over the mailing list. Once
+a patch is submitted to the mailing list, other developers will provide
+feedback to the patch via emails sent through the mailing list.
+
 In the review process, do not hesitate to respond to patch submissions
 for remarks, suggestions or anything that will help everyone to
-understand the patches and make them better.
+understand the patches and make them better. Please use internet
+style replies in plain text emails when responding to patch
+submissions.
 
 Some tags are used to help following the state of any patch posted on
 the mailing-list:
@@ -144,6 +150,10 @@ Acked-by:: Indicates that the patch can be committed.
 Tested-by:: Indicates that the patch has been tested. It is useful
   but not necessary to add a comment about what has been tested.
 
+Buildroot's Patchwork website can be used to pull in patches for testing
+purposes. Please see xref:apply-patches-patchwork[] for more
+information on using Buildroot's Patchwork website to apply patches.
+
 Autobuild
 ---------
 
diff --git a/docs/manual/get-involved.txt b/docs/manual/get-involved.txt
index 8515d34..173b0f4 100644
--- a/docs/manual/get-involved.txt
+++ b/docs/manual/get-involved.txt
@@ -55,11 +55,43 @@ using a code sharing website.
 Patchwork
 ---------
 
-The Buildroot patch management interface is at
+Patchwork is a web-based patch tracking system designed to facilitate
+the contribution and management of contributions to an open-source
+project. Patches that have been sent to a mailing list are \'caught' by
+the system, and appear on a web page. Any comments posted that
+reference the patch are appended to the patch page too. For more
+information on Patchwork see
+http://jk.ozlabs.org/projects/patchwork[].
+
+Buildroot's Patchwork website is mainly for use by the Buildroot's
+maintainer to ensure patches aren't missed. The website however,
+exposes patches and their corresponding review comments in a clean
+and concise web interface.
+
+The Buildroot patch management interface is available at
 http://patchwork.buildroot.org[].
 
-All patches and comments sent through the mailing list are
-automatically indexed in http://patchwork.buildroot.org[patchwork].
+[[apply-patches-patchwork]]
+Applying Patches from Patchwork
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Buildroot's Patchwork website main use for a developer is for pulling
+in patches into their local git repository for testing purposes.
+
+When browsing patches in the patchwork management interface, a +mbox+
+link is provided at the top of the page. Copy this link address and
+run the following commands:
+
+---------------------
+$ git checkout -b <test-branch-name>
+$ wget -O - <mbox-url> | git am
+---------------------
+
+Another option for applying patches is to create a bundle. A bundle is
+a set of patches that you can group together using the patchwork
+interface. Once the bundle is created and the bundle is made public,
+you can copy the +mbox+ link for the bundle and apply the bundle
+using the above commands.
 
 [[bugtracker]]
 Bugtracker
-- 
1.7.1

[Buildroot] [PATCH v2 1/1] manual: update review process and patchwork

[Thomas De Schampheleire]

Hi Ryan,

On Wed, Oct 9, 2013 at 2:31 AM, Ryan Barnett
<rjbarnet@rockwellcollins.com> wrote:
> Adding more documentaiton based on discussion from the mailing list
> in regards the buildroot review process and how patchworks can be
> used to pull in patches for testing purposes.
>
> Mailing list discussion:
> http://lists.busybox.net/pipermail/buildroot/2013-September/078170.html
>
> Signed-off-by: Ryan Barnett <rjbarnet@rockwellcollins.com>
>
> ---
>
> v1 -> v2
>  * Updated all references to patchwork to be Patchwork or Buildroot's
>    Patchwork instead of a few misspellings (suggested by Thomas
>    Petazzoni)
>  * Added clarification that patchwork main use is for the Buildroot
>    maintainer (suggested by Thomas Petazzoni)
>
> Signed-off-by: Ryan Barnett <rjbarnet@rockwellcollins.com>
> ---
>  docs/manual/contribute.txt   |   12 +++++++++++-
>  docs/manual/get-involved.txt |   38 +++++++++++++++++++++++++++++++++++---
>  2 files changed, 46 insertions(+), 4 deletions(-)
>
> diff --git a/docs/manual/contribute.txt b/docs/manual/contribute.txt
> index 2b2783d..201685c 100644
> --- a/docs/manual/contribute.txt
> +++ b/docs/manual/contribute.txt
> @@ -132,9 +132,15 @@ $ git format-patch --subject-prefix "PATCH v4" \
>  Reviewing/Testing patches
>  -------------------------
>
> +The review process for new patches is done over the mailing list. Once
> +a patch is submitted to the mailing list, other developers will provide
> +feedback to the patch via emails sent through the mailing list.
> +
>  In the review process, do not hesitate to respond to patch submissions
>  for remarks, suggestions or anything that will help everyone to
> -understand the patches and make them better.
> +understand the patches and make them better. Please use internet
> +style replies in plain text emails when responding to patch
> +submissions.
>
>  Some tags are used to help following the state of any patch posted on
>  the mailing-list:
> @@ -144,6 +150,10 @@ Acked-by:: Indicates that the patch can be committed.
>  Tested-by:: Indicates that the patch has been tested. It is useful
>    but not necessary to add a comment about what has been tested.
>
> +Buildroot's Patchwork website can be used to pull in patches for testing
> +purposes. Please see xref:apply-patches-patchwork[] for more
> +information on using Buildroot's Patchwork website to apply patches.
> +
>  Autobuild
>  ---------
>
> diff --git a/docs/manual/get-involved.txt b/docs/manual/get-involved.txt
> index 8515d34..173b0f4 100644
> --- a/docs/manual/get-involved.txt
> +++ b/docs/manual/get-involved.txt
> @@ -55,11 +55,43 @@ using a code sharing website.
>  Patchwork
>  ---------
>
> -The Buildroot patch management interface is at
> +Patchwork is a web-based patch tracking system designed to facilitate
> +the contribution and management of contributions to an open-source
> +project. Patches that have been sent to a mailing list are \'caught' by
> +the system, and appear on a web page. Any comments posted that
> +reference the patch are appended to the patch page too. For more
> +information on Patchwork see
> +http://jk.ozlabs.org/projects/patchwork[].
> +
> +Buildroot's Patchwork website is mainly for use by the Buildroot's
> +maintainer to ensure patches aren't missed. The website however,
> +exposes patches and their corresponding review comments in a clean
> +and concise web interface.
> +
> +The Buildroot patch management interface is available at
>  http://patchwork.buildroot.org[].
>
> -All patches and comments sent through the mailing list are
> -automatically indexed in http://patchwork.buildroot.org[patchwork].
> +[[apply-patches-patchwork]]
> +Applying Patches from Patchwork
> +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> +
> +Buildroot's Patchwork website main use for a developer is for pulling
> +in patches into their local git repository for testing purposes.
> +
> +When browsing patches in the patchwork management interface, a +mbox+

shouldn't this be 'an mbox' because you pronounce mbox as embox ?


Best regards,
Thomas

[Buildroot] [PATCH v2 1/1] manual: update review process and patchwork

[Thomas Petazzoni]

Dear Ryan Barnett,

On Tue, 8 Oct 2013 19:31:51 -0500, Ryan Barnett wrote:
> Adding more documentaiton based on discussion from the mailing list
> in regards the buildroot review process and how patchworks can be
> used to pull in patches for testing purposes.
> 
> Mailing list discussion:
> http://lists.busybox.net/pipermail/buildroot/2013-September/078170.html
> 
> Signed-off-by: Ryan Barnett <rjbarnet@rockwellcollins.com>

Acked-by: Thomas Petazzoni <thomas.petazzoni@free-electrons.com>
-- 
Thomas Petazzoni, Free Electrons
Embedded Linux, Kernel and Android engineering
http://free-electrons.com

[Buildroot] [PATCH v2 1/1] manual: update review process and patchwork

[Samuel Martin]

Hi Ryan,


2013/10/9 Ryan Barnett <rjbarnet@rockwellcollins.com>

> Adding more documentaiton based on discussion from the mailing list
> in regards the buildroot review process and how patchworks can be
> used to pull in patches for testing purposes.
>
> Mailing list discussion:
> http://lists.busybox.net/pipermail/buildroot/2013-September/078170.html
>
> Signed-off-by: Ryan Barnett <rjbarnet@rockwellcollins.com>
>
> ---
>
> v1 -> v2
>  * Updated all references to patchwork to be Patchwork or Buildroot's
>    Patchwork instead of a few misspellings (suggested by Thomas
>    Petazzoni)
>  * Added clarification that patchwork main use is for the Buildroot
>    maintainer (suggested by Thomas Petazzoni)
>
> Signed-off-by: Ryan Barnett <rjbarnet@rockwellcollins.com>
> ---
>  docs/manual/contribute.txt   |   12 +++++++++++-
>  docs/manual/get-involved.txt |   38 +++++++++++++++++++++++++++++++++++---
>  2 files changed, 46 insertions(+), 4 deletions(-)
>
> diff --git a/docs/manual/contribute.txt b/docs/manual/contribute.txt
> index 2b2783d..201685c 100644
> --- a/docs/manual/contribute.txt
> +++ b/docs/manual/contribute.txt
> @@ -132,9 +132,15 @@ $ git format-patch --subject-prefix "PATCH v4" \
>  Reviewing/Testing patches
>  -------------------------
>
> +The review process for new patches is done over the mailing list. Once
> +a patch is submitted to the mailing list, other developers will provide
> +feedback to the patch via emails sent through the mailing list.
> +
>  In the review process, do not hesitate to respond to patch submissions
>  for remarks, suggestions or anything that will help everyone to
> -understand the patches and make them better.
> +understand the patches and make them better. Please use internet
> +style replies in plain text emails when responding to patch
> +submissions.
>
>  Some tags are used to help following the state of any patch posted on
>  the mailing-list:
> @@ -144,6 +150,10 @@ Acked-by:: Indicates that the patch can be committed.
>  Tested-by:: Indicates that the patch has been tested. It is useful
>    but not necessary to add a comment about what has been tested.
>
> +Buildroot's Patchwork website can be used to pull in patches for testing
> +purposes. Please see xref:apply-patches-patchwork[] for more
> +information on using Buildroot's Patchwork website to apply patches.
> +
>  Autobuild
>  ---------
>
> diff --git a/docs/manual/get-involved.txt b/docs/manual/get-involved.txt
> index 8515d34..173b0f4 100644
> --- a/docs/manual/get-involved.txt
> +++ b/docs/manual/get-involved.txt
> @@ -55,11 +55,43 @@ using a code sharing website.
>  Patchwork
>  ---------
>
> -The Buildroot patch management interface is at
> +Patchwork is a web-based patch tracking system designed to facilitate
> +the contribution and management of contributions to an open-source
> +project. Patches that have been sent to a mailing list are \'caught' by
> +the system, and appear on a web page. Any comments posted that
> +reference the patch are appended to the patch page too. For more
> +information on Patchwork see
> +http://jk.ozlabs.org/projects/patchwork[].
> +
> +Buildroot's Patchwork website is mainly for use by the Buildroot's
> +maintainer to ensure patches aren't missed. The website however,
> +exposes patches and their corresponding review comments in a clean
> +and concise web interface.
> +
> +The Buildroot patch management interface is available at
>  http://patchwork.buildroot.org[].
>
> -All patches and comments sent through the mailing list are
> -automatically indexed in http://patchwork.buildroot.org[patchwork].
> +[[apply-patches-patchwork]]
> +Applying Patches from Patchwork
> +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
>
Not sure the capital "P" is needed for "Patches".


>  +
> +Buildroot's Patchwork website main use for a developer is for pulling
> +in patches into their local git repository for testing purposes.
> +
> +When browsing patches in the patchwork management interface, a +mbox+
> +link is provided at the top of the page. Copy this link address and
> +run the following commands:
> +
> +---------------------
> +$ git checkout -b <test-branch-name>
> +$ wget -O - <mbox-url> | git am
> +---------------------
> +
> +Another option for applying patches is to create a bundle. A bundle is
> +a set of patches that you can group together using the patchwork
> +interface. Once the bundle is created and the bundle is made public,
> +you can copy the +mbox+ link for the bundle and apply the bundle
> +using the above commands.
>
>
Otherwise, you have my ack:
Acked-by: "Samuel Martin" <s.martin49@gmail.com>

Regards,

-- 
Samuel
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.busybox.net/pipermail/buildroot/attachments/20131009/b80d43b0/attachment-0001.html>

[Buildroot] [PATCH v2 1/1] manual: update review process and patchwork

[Ryan Barnett]

Thomas D.,

Thomas De Schampheleire <patrickdepinguin@gmail.com> wrote on 10/09/2013 
01:50:57 AM:

> Hi Ryan,
> 
> On Wed, Oct 9, 2013 at 2:31 AM, Ryan Barnett
> <rjbarnet@rockwellcollins.com> wrote:
> > Adding more documentaiton based on discussion from the mailing list
> > in regards the buildroot review process and how patchworks can be
> > used to pull in patches for testing purposes.
> >
> > Mailing list discussion:
> > 
http://lists.busybox.net/pipermail/buildroot/2013-September/078170.html
> >
> > Signed-off-by: Ryan Barnett <rjbarnet@rockwellcollins.com>
> >
> > ---
> >
> > v1 -> v2
> >  * Updated all references to patchwork to be Patchwork or Buildroot's
> >    Patchwork instead of a few misspellings (suggested by Thomas
> >    Petazzoni)
> >  * Added clarification that patchwork main use is for the Buildroot
> >    maintainer (suggested by Thomas Petazzoni)
> >
> > Signed-off-by: Ryan Barnett <rjbarnet@rockwellcollins.com>
> > ---
> >  docs/manual/contribute.txt   |   12 +++++++++++-
> >  docs/manual/get-involved.txt |   38 
+++++++++++++++++++++++++++++++++++---
> >  2 files changed, 46 insertions(+), 4 deletions(-)
> >
> > diff --git a/docs/manual/contribute.txt b/docs/manual/contribute.txt
> > index 2b2783d..201685c 100644
> > --- a/docs/manual/contribute.txt
> > +++ b/docs/manual/contribute.txt
> > @@ -132,9 +132,15 @@ $ git format-patch --subject-prefix "PATCH v4" \
> >  Reviewing/Testing patches
> >  -------------------------
> >
> > +The review process for new patches is done over the mailing list. 
Once
> > +a patch is submitted to the mailing list, other developers will 
provide
> > +feedback to the patch via emails sent through the mailing list.
> > +
> >  In the review process, do not hesitate to respond to patch 
submissions
> >  for remarks, suggestions or anything that will help everyone to
> > -understand the patches and make them better.
> > +understand the patches and make them better. Please use internet
> > +style replies in plain text emails when responding to patch
> > +submissions.
> >
> >  Some tags are used to help following the state of any patch posted on
> >  the mailing-list:
> > @@ -144,6 +150,10 @@ Acked-by:: Indicates that the patch can be 
committed.
> >  Tested-by:: Indicates that the patch has been tested. It is useful
> >    but not necessary to add a comment about what has been tested.
> >
> > +Buildroot's Patchwork website can be used to pull in patches for 
testing
> > +purposes. Please see xref:apply-patches-patchwork[] for more
> > +information on using Buildroot's Patchwork website to apply patches.
> > +
> >  Autobuild
> >  ---------
> >
> > diff --git a/docs/manual/get-involved.txt 
b/docs/manual/get-involved.txt
> > index 8515d34..173b0f4 100644
> > --- a/docs/manual/get-involved.txt
> > +++ b/docs/manual/get-involved.txt
> > @@ -55,11 +55,43 @@ using a code sharing website.
> >  Patchwork
> >  ---------
> >
> > -The Buildroot patch management interface is at
> > +Patchwork is a web-based patch tracking system designed to facilitate
> > +the contribution and management of contributions to an open-source
> > +project. Patches that have been sent to a mailing list are \'caught' 
by
> > +the system, and appear on a web page. Any comments posted that
> > +reference the patch are appended to the patch page too. For more
> > +information on Patchwork see
> > +http://jk.ozlabs.org/projects/patchwork[].
> > +
> > +Buildroot's Patchwork website is mainly for use by the Buildroot's
> > +maintainer to ensure patches aren't missed. The website however,
> > +exposes patches and their corresponding review comments in a clean
> > +and concise web interface.
> > +
> > +The Buildroot patch management interface is available at
> >  http://patchwork.buildroot.org[].
> >
> > -All patches and comments sent through the mailing list are
> > -automatically indexed in http://patchwork.buildroot.org[patchwork].
> > +[[apply-patches-patchwork]]
> > +Applying Patches from Patchwork
> > +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> > +
> > +Buildroot's Patchwork website main use for a developer is for pulling
> > +in patches into their local git repository for testing purposes.
> > +
> > +When browsing patches in the patchwork management interface, a +mbox+
> 
> shouldn't this be 'an mbox' because you pronounce mbox as embox ?

I was on the fence on this one too and with this question you are now
testing my grammar education from primary school :) I did do a bit of
google research on this and have come to the conclusion that I used 'a'
correctly in this instance. Please see this website which is consider
in the US to be a reputable source for English writing:

https://owl.english.purdue.edu/owl/resource/591/01

> Best regards,
> Thomas

Thanks,
-Ryan

[Buildroot] [PATCH v2 1/1] manual: update review process and patchwork

[Thomas De Schampheleire]

Hi Ryan,

On Wed, Oct 9, 2013 at 3:01 PM, Ryan Barnett
<rjbarnet@rockwellcollins.com> wrote:
>> > +
>> > +When browsing patches in the patchwork management interface, a +mbox+
>>
>> shouldn't this be 'an mbox' because you pronounce mbox as embox ?
>
> I was on the fence on this one too and with this question you are now
> testing my grammar education from primary school :) I did do a bit of
> google research on this and have come to the conclusion that I used 'a'
> correctly in this instance. Please see this website which is consider
> in the US to be a reputable source for English writing:
>
> https://owl.english.purdue.edu/owl/resource/591/01

It seems we differ in the conclusion after reading the link you provided :)
Here is the excerpt that makes me conclude it should be 'an':

-----
The choice of article is actually based upon the phonetic (sound)
quality of the first letter in a word, not on the orthographic
(written) representation of the letter. If the first letter makes a
vowel-type sound, you use "an"; if the first letter would make a
consonant-type sound, you use "a."
-----

Since mbox is short for mailbox, the m is actually an acronym. Hence
we pronounce it as 'embox' not 'mmmbox'. Do you agree on this or do
you pronounce it differently?

So the phonetic quality of the first letter is 'e', a vowel-type
sound, and hence requires the 'an' article.
The link you showed does not explicitly describe the situation in case
of acronym, though.

I believe it is the same as:
an MBA program
an NBA basketball player
an NSA employee
an nvidia driver

Although less reputable than the link you provided, the following
sites back me up on this:
http://en.wikipedia.org/wiki/English_articles#Distinction_between_a_and_an
http://editingandwritingservices.com/using-articles-with-abbreviations/
http://www.scribendi.com/advice/the_correct_use_of_acronyms.en.html

Best regards,
Thomas

[Buildroot] [PATCH v2 1/1] manual: update review process and patchwork

[Ryan Barnett]

Thomas D.,

Thomas De Schampheleire <patrickdepinguin@gmail.com> wrote on 10/09/2013 
08:24:43 AM:

> Hi Ryan,
> 
> On Wed, Oct 9, 2013 at 3:01 PM, Ryan Barnett
> <rjbarnet@rockwellcollins.com> wrote:
> >> > +
> >> > +When browsing patches in the patchwork management interface, a 
+mbox+
> >>
> >> shouldn't this be 'an mbox' because you pronounce mbox as embox ?
> >
> > I was on the fence on this one too and with this question you are now
> > testing my grammar education from primary school :) I did do a bit of
> > google research on this and have come to the conclusion that I used 
'a'
> > correctly in this instance. Please see this website which is consider
> > in the US to be a reputable source for English writing:
> >
> > https://owl.english.purdue.edu/owl/resource/591/01
> 
> It seems we differ in the conclusion after reading the link you provided 
:)
> Here is the excerpt that makes me conclude it should be 'an':

I agree now with you and will fix. See below for more comments.

> -----
> The choice of article is actually based upon the phonetic (sound)
> quality of the first letter in a word, not on the orthographic
> (written) representation of the letter. If the first letter makes a
> vowel-type sound, you use "an"; if the first letter would make a
> consonant-type sound, you use "a."
> -----
> 
> Since mbox is short for mailbox, the m is actually an acronym. Hence
> we pronounce it as 'embox' not 'mmmbox'. Do you agree on this or do
> you pronounce it differently?

I guess I wasn't thinking of it in terms of an acronym. With that case
then I do agree with you that it should be 'an'. And to be clear, I do
agree that it is an acronym.

Native English Speaker:              0
English as Second Language Speaker:  1

It's been a long time since I've had to worry about an English grammar
corner like this . I guess I was just automatically fix minor mistakes 
like this in my head and my spell/grammar checker doesn't call me out.

> So the phonetic quality of the first letter is 'e', a vowel-type
> sound, and hence requires the 'an' article.
> The link you showed does not explicitly describe the situation in case
> of acronym, though.
> 
> I believe it is the same as:
> an MBA program
> an NBA basketball player
> an NSA employee
> an nvidia driver

Good examples. Thank you for spending the time on this minor mistake
and in the future I will try to watch this.
 
> Although less reputable than the link you provided, the following
> sites back me up on this:
> 
http://en.wikipedia.org/wiki/English_articles#Distinction_between_a_and_an
> http://editingandwritingservices.com/using-articles-with-abbreviations/
> http://www.scribendi.com/advice/the_correct_use_of_acronyms.en.html
> 
> Best regards,
> Thomas

Thanks,
-Ryan
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.busybox.net/pipermail/buildroot/attachments/20131009/ca5b1fc8/attachment.html>