[Buildroot] [PATCH 0 of 8] manual: rework Contributing chapter

[Buildroot] [PATCH 0 of 8] manual: rework Contributing chapter

[Thomas De Schampheleire]

This patch series reworks the "Contributing to Buildroot" chapter in the
manual. According to the latest Buildroot Developer Days, we want to promote
contributions that are not feature patches, like fixing autobuild failures,
closing bugs, working on items from the TODO list, etc. This series reorders
and expands the chapter with that desire in mind.

Signed-off-by: Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>

---
 docs/manual/contribute.txt |  334 ++++++++++++++++++++++++----------------
 1 files changed, 196 insertions(+), 138 deletions(-)

[Buildroot] [PATCH 1 of 8] manual: contributing: expand introduction

[Thomas De Schampheleire]

This patch expands the introduction of the "Contributing to buildroot"
section. In general, the intention of this and subsequent patches is to
promote non-feature contributions, like autobuild fixes, bug report
analysis, TODO list work, etc.

Signed-off-by: Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>

---
 docs/manual/contribute.txt |  31 ++++++++++++++++++++-----------
 1 files changed, 20 insertions(+), 11 deletions(-)

diff --git a/docs/manual/contribute.txt b/docs/manual/contribute.txt
--- a/docs/manual/contribute.txt
+++ b/docs/manual/contribute.txt
@@ -2,26 +2,35 @@
 // vim: set syntax=asciidoc:
 
 Contributing to Buildroot
-========================
+=========================
 
-If you want to contribute to Buildroot, you will need a git view of
-the project. Refer to xref:getting-buildroot[] to get it.
+There are many ways in which you can contribute to Buildroot: analyzing
+and fixing bugs, analyzing and fixing package build failures detected by
+the autobuilders, testing and reviewing patches sent by other
+developers, working on the items in our TODO list and sending your own
+improvements to Buildroot or its manual. The following sections give a
+little more detail on each of these items.
 
-Currently, the mailing list is the central place for contribution.
-If you have not already subscribed to it, then refer to
+If you are interested in contributing to Buildroot, the first thing you
+should do is to subscribe to the Buildroot mailing list. This list is
+the main way of interacting with other Buildroot developers and to send
+contributions to. If you aren't subscribed yet, then refer to
 xref:mailing-list-subscribe[].
 
-Recently, a web interface is also used to manage patches sent to the
-mailing list, see xref:patchwork[].
-
-[NOTE]
-_Please, do not attach patches to bugs, send them to the mailing list
-instead_ (see xref:submitting-patches[]).
+If you are going to touch the code, it is highly recommended to use a
+git repository of Buildroot, rather than starting from an extracted
+source code tarball. Git is the easiest way to develop from and directly
+send your patches to the mailing list. Refer to xref:getting-buildroot[]
+for more information on obtaining a Buildroot git tree.
 
 [[submitting-patches]]
 Submitting patches
 ------------------
 
+[NOTE]
+_Please, do not attach patches to bugs, send them to the mailing list
+instead_.
+
 When your changes are done, and committed in your local git view,
 _rebase_ your development branch on top of the upstream tree before
 generating the patch set. To do so, run:

[Buildroot] [PATCH 1 of 8] manual: contributing: expand introduction

[Yann E. MORIN]

Thomas, All,

On 2014-03-05 17:24 +0100, Thomas De Schampheleire spake thusly:
> This patch expands the introduction of the "Contributing to buildroot"
> section. In general, the intention of this and subsequent patches is to
> promote non-feature contributions, like autobuild fixes, bug report
> analysis, TODO list work, etc.
> 
> Signed-off-by: Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>

Reviewed-by: "Yann E. MORIN" <yann.morin.1998@free.fr>

Regards,
Yann E. MORIN.

> ---
>  docs/manual/contribute.txt |  31 ++++++++++++++++++++-----------
>  1 files changed, 20 insertions(+), 11 deletions(-)
> 
> diff --git a/docs/manual/contribute.txt b/docs/manual/contribute.txt
> --- a/docs/manual/contribute.txt
> +++ b/docs/manual/contribute.txt
> @@ -2,26 +2,35 @@
>  // vim: set syntax=asciidoc:
>  
>  Contributing to Buildroot
> -========================
> +=========================
>  
> -If you want to contribute to Buildroot, you will need a git view of
> -the project. Refer to xref:getting-buildroot[] to get it.
> +There are many ways in which you can contribute to Buildroot: analyzing
> +and fixing bugs, analyzing and fixing package build failures detected by
> +the autobuilders, testing and reviewing patches sent by other
> +developers, working on the items in our TODO list and sending your own
> +improvements to Buildroot or its manual. The following sections give a
> +little more detail on each of these items.
>  
> -Currently, the mailing list is the central place for contribution.
> -If you have not already subscribed to it, then refer to
> +If you are interested in contributing to Buildroot, the first thing you
> +should do is to subscribe to the Buildroot mailing list. This list is
> +the main way of interacting with other Buildroot developers and to send
> +contributions to. If you aren't subscribed yet, then refer to
>  xref:mailing-list-subscribe[].
>  
> -Recently, a web interface is also used to manage patches sent to the
> -mailing list, see xref:patchwork[].
> -
> -[NOTE]
> -_Please, do not attach patches to bugs, send them to the mailing list
> -instead_ (see xref:submitting-patches[]).
> +If you are going to touch the code, it is highly recommended to use a
> +git repository of Buildroot, rather than starting from an extracted
> +source code tarball. Git is the easiest way to develop from and directly
> +send your patches to the mailing list. Refer to xref:getting-buildroot[]
> +for more information on obtaining a Buildroot git tree.
>  
>  [[submitting-patches]]
>  Submitting patches
>  ------------------
>  
> +[NOTE]
> +_Please, do not attach patches to bugs, send them to the mailing list
> +instead_.
> +
>  When your changes are done, and committed in your local git view,
>  _rebase_ your development branch on top of the upstream tree before
>  generating the patch set. To do so, run:
> _______________________________________________
> buildroot mailing list
> buildroot at busybox.net
> http://lists.busybox.net/mailman/listinfo/buildroot

-- 
.-----------------.--------------------.------------------.--------------------.
|  Yann E. MORIN  | Real-Time Embedded | /"\ ASCII RIBBON | Erics' conspiracy: |
| +33 662 376 056 | Software  Designer | \ / CAMPAIGN     |  ___               |
| +33 223 225 172 `------------.-------:  X  AGAINST      |  \e/  There is no  |
| http://ymorin.is-a-geek.org/ | _/*\_ | / \ HTML MAIL    |   v   conspiracy.  |
'------------------------------^-------^------------------^--------------------'

[Buildroot] [PATCH 1 of 8] manual: contributing: expand introduction

[Samuel Martin]

On Wed, Mar 5, 2014 at 6:11 PM, Yann E. MORIN <yann.morin.1998@free.fr> wrote:
> Thomas, All,
>
> On 2014-03-05 17:24 +0100, Thomas De Schampheleire spake thusly:
>> This patch expands the introduction of the "Contributing to buildroot"
>> section. In general, the intention of this and subsequent patches is to
>> promote non-feature contributions, like autobuild fixes, bug report
>> analysis, TODO list work, etc.
>>
>> Signed-off-by: Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
>
> Reviewed-by: "Yann E. MORIN" <yann.morin.1998@free.fr>

Acked-by: Samuel Martin <s.martin49@gmail.com>

Regards,

-- 
Samuel

[Buildroot] [PATCH 2 of 8] manual: contributing: add section on analyzing bug reports

[Thomas De Schampheleire]

This patch adds a small section to the manual promoting the reproduction,
analysis and fixing of bug reports.

Signed-off-by: Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>

---
 docs/manual/contribute.txt |  10 ++++++++++
 1 files changed, 10 insertions(+), 0 deletions(-)

diff --git a/docs/manual/contribute.txt b/docs/manual/contribute.txt
--- a/docs/manual/contribute.txt
+++ b/docs/manual/contribute.txt
@@ -23,6 +23,16 @@ source code tarball. Git is the easiest 
 send your patches to the mailing list. Refer to xref:getting-buildroot[]
 for more information on obtaining a Buildroot git tree.
 
+Reproducing, analyzing and fixing bugs
+--------------------------------------
+
+A first way of contributing is to have a look at the open bug reports in
+the https://bugs.busybox.net/buglist.cgi?product=buildroot[Buildroot bug
+tracker]. As we strive to keep the bug count as small as possible, all
+help in reproducing, analyzing and fixing reported bugs is more than
+welcome. Don't hesitate to add a comment to bug reports reporting your
+findings, even if you don't yet see the full picture.
+
 [[submitting-patches]]
 Submitting patches
 ------------------

[Buildroot] [PATCH 2 of 8] manual: contributing: add section on analyzing bug reports

[Yann E. MORIN]

Thomas, All,

On 2014-03-05 17:24 +0100, Thomas De Schampheleire spake thusly:
> This patch adds a small section to the manual promoting the reproduction,
> analysis and fixing of bug reports.
> 
> Signed-off-by: Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>

Reviewed-by: "Yann E. MORIN" <yann.morin.1998@free.fr>

Regards,
Yann E. MORIN.

> ---
>  docs/manual/contribute.txt |  10 ++++++++++
>  1 files changed, 10 insertions(+), 0 deletions(-)
> 
> diff --git a/docs/manual/contribute.txt b/docs/manual/contribute.txt
> --- a/docs/manual/contribute.txt
> +++ b/docs/manual/contribute.txt
> @@ -23,6 +23,16 @@ source code tarball. Git is the easiest 
>  send your patches to the mailing list. Refer to xref:getting-buildroot[]
>  for more information on obtaining a Buildroot git tree.
>  
> +Reproducing, analyzing and fixing bugs
> +--------------------------------------
> +
> +A first way of contributing is to have a look at the open bug reports in
> +the https://bugs.busybox.net/buglist.cgi?product=buildroot[Buildroot bug
> +tracker]. As we strive to keep the bug count as small as possible, all
> +help in reproducing, analyzing and fixing reported bugs is more than
> +welcome. Don't hesitate to add a comment to bug reports reporting your
> +findings, even if you don't yet see the full picture.
> +
>  [[submitting-patches]]
>  Submitting patches
>  ------------------
> _______________________________________________
> buildroot mailing list
> buildroot at busybox.net
> http://lists.busybox.net/mailman/listinfo/buildroot

-- 
.-----------------.--------------------.------------------.--------------------.
|  Yann E. MORIN  | Real-Time Embedded | /"\ ASCII RIBBON | Erics' conspiracy: |
| +33 662 376 056 | Software  Designer | \ / CAMPAIGN     |  ___               |
| +33 223 225 172 `------------.-------:  X  AGAINST      |  \e/  There is no  |
| http://ymorin.is-a-geek.org/ | _/*\_ | / \ HTML MAIL    |   v   conspiracy.  |
'------------------------------^-------^------------------^--------------------'

[Buildroot] [PATCH 2 of 8] manual: contributing: add section on analyzing bug reports

[Samuel Martin]

On Wed, Mar 5, 2014 at 6:37 PM, Yann E. MORIN <yann.morin.1998@free.fr> wrote:
> Thomas, All,
>
> On 2014-03-05 17:24 +0100, Thomas De Schampheleire spake thusly:
>> This patch adds a small section to the manual promoting the reproduction,
>> analysis and fixing of bug reports.
>>
>> Signed-off-by: Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
>
> Reviewed-by: "Yann E. MORIN" <yann.morin.1998@free.fr>

Acked-by: Samuel Martin <s.martin49@gmail.com>

Regards,

-- 
Samuel

[Buildroot] [PATCH 3 of 8] manual: contributing: move and expand autobuild section

[Thomas De Schampheleire]

This patch moves the section about autobuild fixing up, and expands it with
more details about what autobuilds are, and how you can help with it.

Signed-off-by: Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>

---
 docs/manual/contribute.txt |  59 +++++++++++++++++++++++++++++------------
 1 files changed, 42 insertions(+), 17 deletions(-)

diff --git a/docs/manual/contribute.txt b/docs/manual/contribute.txt
--- a/docs/manual/contribute.txt
+++ b/docs/manual/contribute.txt
@@ -33,6 +33,48 @@ help in reproducing, analyzing and fixin
 welcome. Don't hesitate to add a comment to bug reports reporting your
 findings, even if you don't yet see the full picture.
 
+Analyzing and fixing autobuild failures
+---------------------------------------
+
+The Buildroot autobuilders are a set of build machines that continuously
+run Buildroot builds based on random configurations. This is done for
+all architectures supported by Buildroot, with various toolchains, and
+with a random selection of packages. With the large commit activity on
+Buildroot, these autobuilders are a great help in detecting problems
+very early after commit.
+
+All build results are available at http://autobuild.buildroot.org[],
+statistics are at http://autobuild.buildroot.org/stats.php[]. Every day,
+an overview of all failed packages is sent to the mailing list.
+
+Detecting problems is great, but obviously these problems have to be
+fixed as well. Your contribution is very welcome here! There are
+basically two things that can be done:
+
+- Analyzing the problems. The daily summary mails do not contain details
+  about the actual failures: in order to see what's going on you have to
+  open the build log and check the last output. Having someone doing
+  this for all packages in the mail is very useful for other developers,
+  as they can make a quick initial analysis based on this output alone.
+
+- Fixing a problem. When fixing autobuild failures, you should follow
+  these steps:
+  . Check if you can reproduce the problem by building with the same
+    configuration.
+  . Analyze the problem and create a fix.
+  . Verify that the problem is really fixed by starting from a clean
+    Buildroot tree and only applying your fix.
+  . Send the fix to the Buildroot mailing list (see
+    xref:submitting-patches[]). In case you created a patch against the
+    package sources, you should also send the patch upstream so that the
+    problem will be fixed in a later release, and the patch in Buildroot
+    can be removed.
+    In the commit message of a patch fixing an autobuild failure, add a
+    reference to the build result directory, as follows:
+---------------------
+Fixes http://autobuild.buildroot.org/results/51000a9d4656afe9e0ea6f07b9f8ed374c2e4069
+---------------------
+
 [[submitting-patches]]
 Submitting patches
 ------------------
@@ -210,23 +252,6 @@ Buildroot's Patchwork website can be use
 purposes. Please see xref:apply-patches-patchwork[] for more
 information on using Buildroot's Patchwork website to apply patches.
 
-Autobuild
----------
-
-The Buildroot community is currently setting up automatic builds in
-order to test more and more configurations. All build results are
-available at http://autobuild.buildroot.org[]
-
-A good way to contribute is by fixing broken builds.
-
-In the commit message of a patch fixing an _autobuild_, add a
-reference to the _build result directory_ (the +dir+ link in the _data
-column_):
-
----------------------
-Fixes http://autobuild.buildroot.org/results/51000a9d4656afe9e0ea6f07b9f8ed374c2e4069
----------------------
-
 [[reporting-bugs]]
 Reporting issues/bugs, get help
 -------------------------------

[Buildroot] [PATCH 3 of 8] manual: contributing: move and expand autobuild section

[Yann E. MORIN]

Thomas, All,

On 2014-03-05 17:24 +0100, Thomas De Schampheleire spake thusly:
> This patch moves the section about autobuild fixing up, and expands it with
> more details about what autobuilds are, and how you can help with it.
[--SNIP--]
> +- Fixing a problem. When fixing autobuild failures, you should follow
> +  these steps:
> +  . Check if you can reproduce the problem by building with the same
> +    configuration.

We could have a pointer to the script from the autobuilders' repository:
    http://git.buildroot.org/buildroot-test/tree/utils/br-reproduce-build

Regards,
Yann E. MORIN.

-- 
.-----------------.--------------------.------------------.--------------------.
|  Yann E. MORIN  | Real-Time Embedded | /"\ ASCII RIBBON | Erics' conspiracy: |
| +33 662 376 056 | Software  Designer | \ / CAMPAIGN     |  ___               |
| +33 223 225 172 `------------.-------:  X  AGAINST      |  \e/  There is no  |
| http://ymorin.is-a-geek.org/ | _/*\_ | / \ HTML MAIL    |   v   conspiracy.  |
'------------------------------^-------^------------------^--------------------'

[Buildroot] [PATCH 4 of 8] manual: contributing: move section on patch reviews up and change intro

[Thomas De Schampheleire]

This patch moves the section about patch reviews and the
Tested-by/Reviewed-by/Acked-by tags upwards. Additionally, the first
paragraph is removed and replaced by another one. There are no other changes
in the text.

Signed-off-by: Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>

---
 docs/manual/contribute.txt |  127 ++++++++++++++++++++--------------------
 1 files changed, 65 insertions(+), 62 deletions(-)

diff --git a/docs/manual/contribute.txt b/docs/manual/contribute.txt
--- a/docs/manual/contribute.txt
+++ b/docs/manual/contribute.txt
@@ -75,6 +75,71 @@ basically two things that can be done:
 Fixes http://autobuild.buildroot.org/results/51000a9d4656afe9e0ea6f07b9f8ed374c2e4069
 ---------------------
 
+Reviewing and testing patches
+-----------------------------
+
+With the amount of patches sent to the mailing list each day, the
+maintainer has a very hard job in judging which patches are ready to
+apply and which aren't. Contributors can greatly help here by reviewing
+and testing these patches, and providing the appropriate Tested-by,
+Reviewed-by, or Acked-by tags (see below).
+
+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. 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:
+
+Tested-by:: Indicates that the patch has been tested in one way or
+  another. You are encouraged to specify what kind of testing you
+  performed (compile-test on architecture X and Y, runtime test on
+  target A, ...). This additional information helps other testers and
+  the maintainer.
+
+Reviewed-by:: Indicates that you code-reviewed the patch and did your
+  best in spotting problems, but you are not sufficiently familiar with
+  the area touched to provide an Acked-by tag. This means that there
+  may be remaining problems in the patch that would be spotted by
+  someone with more experience in that area. Should such problems be
+  detected, your Reviewed-by tag remains appropriate and you cannot
+  be blamed.
+
+Acked-by:: Indicates that you code-reviewed the patch and you are
+familiar enough with the area touched to feel that the patch can be
+committed as-is (no additional changes required). In case it later turns
+out that something is wrong with the patch, your Acked-by could be
+considered inappropriate. The difference between Acked-by and
+Reviewed-by is thus mainly that you are prepared to take the blame on
+Acked patches, but not on Reviewed ones.
+
+If you reviewed a patch and have comments on it, you should simply reply
+to the patch stating these comments, without providing a Reviewed-by or
+Acked-by tag. These tags should only be provided if you judge the patch
+to be good as it is.
+
+It is important to note that neither Reviewed-by nor Acked-by imply
+that testing has been performed. To indicate that you both reviewed and
+tested the patch, provide two separate tags (Reviewed/Acked-by and
+Tested-by).
+
+Note also that _any developer_ can provide Tested/Reviewed/Acked-by
+tags, without exception, and we encourage everyone to do this. Buildroot
+does not have a defined group of _core_ developers, it just so happens
+that some developers are more active than others. The maintainer will
+value tags according to the track record of their submitter. Tags
+provided by a regular contributor will naturally be trusted more than
+tags provided by a newcomer. As you provide tags more regularly, your
+'trustworthiness' (in the eyes of the maintainer) will go up, but _any_
+tag provided is valuable.
+
+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.
+
+
 [[submitting-patches]]
 Submitting patches
 ------------------
@@ -190,68 +255,6 @@ This can be easily handled with +git for
     -M -o outgoing origin/master
 ---------------------
 
-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. 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:
-
-Tested-by:: Indicates that the patch has been tested in one way or
-  another. You are encouraged to specify what kind of testing you
-  performed (compile-test on architecture X and Y, runtime test on
-  target A, ...). This additional information helps other testers and
-  the maintainer.
-
-Reviewed-by:: Indicates that you code-reviewed the patch and did your
-  best in spotting problems, but you are not sufficiently familiar with
-  the area touched to provide an Acked-by tag. This means that there
-  may be remaining problems in the patch that would be spotted by
-  someone with more experience in that area. Should such problems be
-  detected, your Reviewed-by tag remains appropriate and you cannot
-  be blamed.
-
-Acked-by:: Indicates that you code-reviewed the patch and you are
-familiar enough with the area touched to feel that the patch can be
-committed as-is (no additional changes required). In case it later turns
-out that something is wrong with the patch, your Acked-by could be
-considered inappropriate. The difference between Acked-by and
-Reviewed-by is thus mainly that you are prepared to take the blame on
-Acked patches, but not on Reviewed ones.
-
-If you reviewed a patch and have comments on it, you should simply reply
-to the patch stating these comments, without providing a Reviewed-by or
-Acked-by tag. These tags should only be provided if you judge the patch
-to be good as it is.
-
-It is important to note that neither Reviewed-by nor Acked-by imply
-that testing has been performed. To indicate that you both reviewed and
-tested the patch, provide two separate tags (Reviewed/Acked-by and
-Tested-by).
-
-Note also that _any developer_ can provide Tested/Reviewed/Acked-by
-tags, without exception, and we encourage everyone to do this. Buildroot
-does not have a defined group of _core_ developers, it just so happens
-that some developers are more active than others. The maintainer will
-value tags according to the track record of their submitter. Tags
-provided by a regular contributor will naturally be trusted more than
-tags provided by a newcomer. As you provide tags more regularly, your
-'trustworthiness' (in the eyes of the maintainer) will go up, but _any_
-tag provided is valuable.
-
-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.
-
 [[reporting-bugs]]
 Reporting issues/bugs, get help
 -------------------------------

[Buildroot] [PATCH 4 of 8] manual: contributing: move section on patch reviews up and change intro

[Yann E. MORIN]

Thomas, All,

On 2014-03-05 17:24 +0100, Thomas De Schampheleire spake thusly:
> This patch moves the section about patch reviews and the
> Tested-by/Reviewed-by/Acked-by tags upwards. Additionally, the first
> paragraph is removed and replaced by another one. There are no other changes
> in the text.
> 
> Signed-off-by: Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>

Reviewed-by: "Yann E. MORIN" <yann.morin.1998@free.fr>

Regards,
Yann E. MORIN.

> ---
>  docs/manual/contribute.txt |  127 ++++++++++++++++++++--------------------
>  1 files changed, 65 insertions(+), 62 deletions(-)
> 
> diff --git a/docs/manual/contribute.txt b/docs/manual/contribute.txt
> --- a/docs/manual/contribute.txt
> +++ b/docs/manual/contribute.txt
> @@ -75,6 +75,71 @@ basically two things that can be done:
>  Fixes http://autobuild.buildroot.org/results/51000a9d4656afe9e0ea6f07b9f8ed374c2e4069
>  ---------------------
>  
> +Reviewing and testing patches
> +-----------------------------
> +
> +With the amount of patches sent to the mailing list each day, the
> +maintainer has a very hard job in judging which patches are ready to
> +apply and which aren't. Contributors can greatly help here by reviewing
> +and testing these patches, and providing the appropriate Tested-by,
> +Reviewed-by, or Acked-by tags (see below).
> +
> +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. 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:
> +
> +Tested-by:: Indicates that the patch has been tested in one way or
> +  another. You are encouraged to specify what kind of testing you
> +  performed (compile-test on architecture X and Y, runtime test on
> +  target A, ...). This additional information helps other testers and
> +  the maintainer.
> +
> +Reviewed-by:: Indicates that you code-reviewed the patch and did your
> +  best in spotting problems, but you are not sufficiently familiar with
> +  the area touched to provide an Acked-by tag. This means that there
> +  may be remaining problems in the patch that would be spotted by
> +  someone with more experience in that area. Should such problems be
> +  detected, your Reviewed-by tag remains appropriate and you cannot
> +  be blamed.
> +
> +Acked-by:: Indicates that you code-reviewed the patch and you are
> +familiar enough with the area touched to feel that the patch can be
> +committed as-is (no additional changes required). In case it later turns
> +out that something is wrong with the patch, your Acked-by could be
> +considered inappropriate. The difference between Acked-by and
> +Reviewed-by is thus mainly that you are prepared to take the blame on
> +Acked patches, but not on Reviewed ones.
> +
> +If you reviewed a patch and have comments on it, you should simply reply
> +to the patch stating these comments, without providing a Reviewed-by or
> +Acked-by tag. These tags should only be provided if you judge the patch
> +to be good as it is.
> +
> +It is important to note that neither Reviewed-by nor Acked-by imply
> +that testing has been performed. To indicate that you both reviewed and
> +tested the patch, provide two separate tags (Reviewed/Acked-by and
> +Tested-by).
> +
> +Note also that _any developer_ can provide Tested/Reviewed/Acked-by
> +tags, without exception, and we encourage everyone to do this. Buildroot
> +does not have a defined group of _core_ developers, it just so happens
> +that some developers are more active than others. The maintainer will
> +value tags according to the track record of their submitter. Tags
> +provided by a regular contributor will naturally be trusted more than
> +tags provided by a newcomer. As you provide tags more regularly, your
> +'trustworthiness' (in the eyes of the maintainer) will go up, but _any_
> +tag provided is valuable.
> +
> +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.
> +
> +
>  [[submitting-patches]]
>  Submitting patches
>  ------------------
> @@ -190,68 +255,6 @@ This can be easily handled with +git for
>      -M -o outgoing origin/master
>  ---------------------
>  
> -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. 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:
> -
> -Tested-by:: Indicates that the patch has been tested in one way or
> -  another. You are encouraged to specify what kind of testing you
> -  performed (compile-test on architecture X and Y, runtime test on
> -  target A, ...). This additional information helps other testers and
> -  the maintainer.
> -
> -Reviewed-by:: Indicates that you code-reviewed the patch and did your
> -  best in spotting problems, but you are not sufficiently familiar with
> -  the area touched to provide an Acked-by tag. This means that there
> -  may be remaining problems in the patch that would be spotted by
> -  someone with more experience in that area. Should such problems be
> -  detected, your Reviewed-by tag remains appropriate and you cannot
> -  be blamed.
> -
> -Acked-by:: Indicates that you code-reviewed the patch and you are
> -familiar enough with the area touched to feel that the patch can be
> -committed as-is (no additional changes required). In case it later turns
> -out that something is wrong with the patch, your Acked-by could be
> -considered inappropriate. The difference between Acked-by and
> -Reviewed-by is thus mainly that you are prepared to take the blame on
> -Acked patches, but not on Reviewed ones.
> -
> -If you reviewed a patch and have comments on it, you should simply reply
> -to the patch stating these comments, without providing a Reviewed-by or
> -Acked-by tag. These tags should only be provided if you judge the patch
> -to be good as it is.
> -
> -It is important to note that neither Reviewed-by nor Acked-by imply
> -that testing has been performed. To indicate that you both reviewed and
> -tested the patch, provide two separate tags (Reviewed/Acked-by and
> -Tested-by).
> -
> -Note also that _any developer_ can provide Tested/Reviewed/Acked-by
> -tags, without exception, and we encourage everyone to do this. Buildroot
> -does not have a defined group of _core_ developers, it just so happens
> -that some developers are more active than others. The maintainer will
> -value tags according to the track record of their submitter. Tags
> -provided by a regular contributor will naturally be trusted more than
> -tags provided by a newcomer. As you provide tags more regularly, your
> -'trustworthiness' (in the eyes of the maintainer) will go up, but _any_
> -tag provided is valuable.
> -
> -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.
> -
>  [[reporting-bugs]]
>  Reporting issues/bugs, get help
>  -------------------------------
> _______________________________________________
> buildroot mailing list
> buildroot at busybox.net
> http://lists.busybox.net/mailman/listinfo/buildroot

-- 
.-----------------.--------------------.------------------.--------------------.
|  Yann E. MORIN  | Real-Time Embedded | /"\ ASCII RIBBON | Erics' conspiracy: |
| +33 662 376 056 | Software  Designer | \ / CAMPAIGN     |  ___               |
| +33 223 225 172 `------------.-------:  X  AGAINST      |  \e/  There is no  |
| http://ymorin.is-a-geek.org/ | _/*\_ | / \ HTML MAIL    |   v   conspiracy.  |
'------------------------------^-------^------------------^--------------------'

[Buildroot] [PATCH 4 of 8] manual: contributing: move section on patch reviews up and change intro

[Samuel Martin]

Hi Thomas,

On Wed, Mar 5, 2014 at 6:41 PM, Yann E. MORIN <yann.morin.1998@free.fr> wrote:
> Thomas, All,
>
> On 2014-03-05 17:24 +0100, Thomas De Schampheleire spake thusly:
>> This patch moves the section about patch reviews and the
>> Tested-by/Reviewed-by/Acked-by tags upwards. Additionally, the first
>> paragraph is removed and replaced by another one. There are no other changes
>> in the text.
>>
>> Signed-off-by: Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
>
> Reviewed-by: "Yann E. MORIN" <yann.morin.1998@free.fr>
>
> Regards,
> Yann E. MORIN.
>
>> ---
>>  docs/manual/contribute.txt |  127 ++++++++++++++++++++--------------------
>>  1 files changed, 65 insertions(+), 62 deletions(-)
>>
>> diff --git a/docs/manual/contribute.txt b/docs/manual/contribute.txt
>> --- a/docs/manual/contribute.txt
>> +++ b/docs/manual/contribute.txt
>> @@ -75,6 +75,71 @@ basically two things that can be done:
>>  Fixes http://autobuild.buildroot.org/results/51000a9d4656afe9e0ea6f07b9f8ed374c2e4069
>>  ---------------------
>>
>> +Reviewing and testing patches
>> +-----------------------------
>> +
>> +With the amount of patches sent to the mailing list each day, the
>> +maintainer has a very hard job in judging which patches are ready to
>> +apply and which aren't. Contributors can greatly help here by reviewing
>> +and testing these patches, and providing the appropriate Tested-by,
>> +Reviewed-by, or Acked-by tags (see below).
>> +
>> +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. 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:
>> +
>> +Tested-by:: Indicates that the patch has been tested in one way or
>> +  another. You are encouraged to specify what kind of testing you
>> +  performed (compile-test on architecture X and Y, runtime test on
>> +  target A, ...). This additional information helps other testers and
>> +  the maintainer.
>> +
>> +Reviewed-by:: Indicates that you code-reviewed the patch and did your
>> +  best in spotting problems, but you are not sufficiently familiar with
>> +  the area touched to provide an Acked-by tag. This means that there
>> +  may be remaining problems in the patch that would be spotted by
>> +  someone with more experience in that area. Should such problems be
>> +  detected, your Reviewed-by tag remains appropriate and you cannot
>> +  be blamed.
>> +
>> +Acked-by:: Indicates that you code-reviewed the patch and you are
>> +familiar enough with the area touched to feel that the patch can be
>> +committed as-is (no additional changes required). In case it later turns
>> +out that something is wrong with the patch, your Acked-by could be
>> +considered inappropriate. The difference between Acked-by and
>> +Reviewed-by is thus mainly that you are prepared to take the blame on
>> +Acked patches, but not on Reviewed ones.

A bit nitpicking:
for Tested-by/Reviewed-by the paragraph is indented, why not for Acked-by? ;-)
(well, it is not indented right now)

Regards,

-- 
Samuel

[Buildroot] [PATCH 4 of 8] manual: contributing: move section on patch reviews up and change intro

[Arnout Vandecappelle]

On 05/03/14 17:24, Thomas De Schampheleire wrote:
> This patch moves the section about patch reviews and the
> Tested-by/Reviewed-by/Acked-by tags upwards. Additionally, the first
> paragraph is removed and replaced by another one. There are no other changes
> in the text.
> 
> Signed-off-by: Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>

 nitpicking comments only...

> 
> ---
>  docs/manual/contribute.txt |  127 ++++++++++++++++++++--------------------
>  1 files changed, 65 insertions(+), 62 deletions(-)
> 
> diff --git a/docs/manual/contribute.txt b/docs/manual/contribute.txt
> --- a/docs/manual/contribute.txt
> +++ b/docs/manual/contribute.txt
> @@ -75,6 +75,71 @@ basically two things that can be done:
>  Fixes http://autobuild.buildroot.org/results/51000a9d4656afe9e0ea6f07b9f8ed374c2e4069
>  ---------------------
>  
> +Reviewing and testing patches
> +-----------------------------
> +
> +With the amount of patches sent to the mailing list each day, the
> +maintainer has a very hard job in judging which patches are ready to
> +apply and which aren't. Contributors can greatly help here by reviewing
> +and testing these patches, and providing the appropriate Tested-by,
> +Reviewed-by, or Acked-by tags (see below).

"""
maintainer has a very hard job to judge which patches are ready to apply
and which ones aren't. Contributors can greatly help here by reviewing
and testing these patches.
"""

 The rest of the paragraph makes it look as if you always have to provide
one of these tags.

> +
> +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. 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:

"""
To indicate approval of a patch, there are three formal tags that keep
track of this approval. To add your tag to a patch, reply to it with the
approval tag below the original author's Signed-of-by line. These tags
will be picked up automatically by patchwork (see
ref:apply-patches-patchwork[]) and will be part of the commit log when
the patch is accepted.
"""

> +
> +Tested-by:: Indicates that the patch has been tested in one way or

... has been tested successfully.


 Regards,
 Arnout


> +  another. You are encouraged to specify what kind of testing you
> +  performed (compile-test on architecture X and Y, runtime test on
> +  target A, ...). This additional information helps other testers and
> +  the maintainer.
> +
> +Reviewed-by:: Indicates that you code-reviewed the patch and did your
> +  best in spotting problems, but you are not sufficiently familiar with
> +  the area touched to provide an Acked-by tag. This means that there
> +  may be remaining problems in the patch that would be spotted by
> +  someone with more experience in that area. Should such problems be
> +  detected, your Reviewed-by tag remains appropriate and you cannot
> +  be blamed.
> +
> +Acked-by:: Indicates that you code-reviewed the patch and you are
> +familiar enough with the area touched to feel that the patch can be
> +committed as-is (no additional changes required). In case it later turns
> +out that something is wrong with the patch, your Acked-by could be
> +considered inappropriate. The difference between Acked-by and
> +Reviewed-by is thus mainly that you are prepared to take the blame on
> +Acked patches, but not on Reviewed ones.
> +
> +If you reviewed a patch and have comments on it, you should simply reply
> +to the patch stating these comments, without providing a Reviewed-by or
> +Acked-by tag. These tags should only be provided if you judge the patch
> +to be good as it is.
> +
> +It is important to note that neither Reviewed-by nor Acked-by imply
> +that testing has been performed. To indicate that you both reviewed and
> +tested the patch, provide two separate tags (Reviewed/Acked-by and
> +Tested-by).
> +
> +Note also that _any developer_ can provide Tested/Reviewed/Acked-by
> +tags, without exception, and we encourage everyone to do this. Buildroot
> +does not have a defined group of _core_ developers, it just so happens
> +that some developers are more active than others. The maintainer will
> +value tags according to the track record of their submitter. Tags
> +provided by a regular contributor will naturally be trusted more than
> +tags provided by a newcomer. As you provide tags more regularly, your
> +'trustworthiness' (in the eyes of the maintainer) will go up, but _any_
> +tag provided is valuable.
> +
> +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.
> +
> +
>  [[submitting-patches]]
>  Submitting patches
>  ------------------
> @@ -190,68 +255,6 @@ This can be easily handled with +git for
>      -M -o outgoing origin/master
>  ---------------------
>  
> -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. 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:
> -
> -Tested-by:: Indicates that the patch has been tested in one way or
> -  another. You are encouraged to specify what kind of testing you
> -  performed (compile-test on architecture X and Y, runtime test on
> -  target A, ...). This additional information helps other testers and
> -  the maintainer.
> -
> -Reviewed-by:: Indicates that you code-reviewed the patch and did your
> -  best in spotting problems, but you are not sufficiently familiar with
> -  the area touched to provide an Acked-by tag. This means that there
> -  may be remaining problems in the patch that would be spotted by
> -  someone with more experience in that area. Should such problems be
> -  detected, your Reviewed-by tag remains appropriate and you cannot
> -  be blamed.
> -
> -Acked-by:: Indicates that you code-reviewed the patch and you are
> -familiar enough with the area touched to feel that the patch can be
> -committed as-is (no additional changes required). In case it later turns
> -out that something is wrong with the patch, your Acked-by could be
> -considered inappropriate. The difference between Acked-by and
> -Reviewed-by is thus mainly that you are prepared to take the blame on
> -Acked patches, but not on Reviewed ones.
> -
> -If you reviewed a patch and have comments on it, you should simply reply
> -to the patch stating these comments, without providing a Reviewed-by or
> -Acked-by tag. These tags should only be provided if you judge the patch
> -to be good as it is.
> -
> -It is important to note that neither Reviewed-by nor Acked-by imply
> -that testing has been performed. To indicate that you both reviewed and
> -tested the patch, provide two separate tags (Reviewed/Acked-by and
> -Tested-by).
> -
> -Note also that _any developer_ can provide Tested/Reviewed/Acked-by
> -tags, without exception, and we encourage everyone to do this. Buildroot
> -does not have a defined group of _core_ developers, it just so happens
> -that some developers are more active than others. The maintainer will
> -value tags according to the track record of their submitter. Tags
> -provided by a regular contributor will naturally be trusted more than
> -tags provided by a newcomer. As you provide tags more regularly, your
> -'trustworthiness' (in the eyes of the maintainer) will go up, but _any_
> -tag provided is valuable.
> -
> -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.
> -
>  [[reporting-bugs]]
>  Reporting issues/bugs, get help
>  -------------------------------
> _______________________________________________
> buildroot mailing list
> buildroot at busybox.net
> http://lists.busybox.net/mailman/listinfo/buildroot
> 


-- 
Arnout Vandecappelle                          arnout at mind be
Senior Embedded Software Architect            +32-16-286500
Essensium/Mind                                http://www.mind.be
G.Geenslaan 9, 3001 Leuven, Belgium           BE 872 984 063 RPR Leuven
LinkedIn profile: http://www.linkedin.com/in/arnoutvandecappelle
GPG fingerprint:  7CB5 E4CC 6C2E EFD4 6E3D A754 F963 ECAB 2450 2F1F

[Buildroot] [PATCH 5 of 8] manual: contributing: add section on TODO list

[Thomas De Schampheleire]

This patch adds a small section about working on items from the TODO list.

Signed-off-by: Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>

---
 docs/manual/contribute.txt |  8 ++++++++
 1 files changed, 8 insertions(+), 0 deletions(-)

diff --git a/docs/manual/contribute.txt b/docs/manual/contribute.txt
--- a/docs/manual/contribute.txt
+++ b/docs/manual/contribute.txt
@@ -139,6 +139,14 @@ Buildroot's Patchwork website can be use
 purposes. Please see xref:apply-patches-patchwork[] for more
 information on using Buildroot's Patchwork website to apply patches.
 
+Work on items from the TODO list
+--------------------------------
+If you want to contribute to Buildroot but don't know where to start,
+and you don't like any of the above topics, you can always work on items
+from the http://elinux.org/Buildroot#Todo_list[Buildroot TODO list].
+Don't hesitate to discuss an item first on the mailing list or on IRC.
+Do edit the wiki to indicate when you start working on an item, so we
+avoid duplicate efforts.
 
 [[submitting-patches]]
 Submitting patches

[Buildroot] [PATCH 5 of 8] manual: contributing: add section on TODO list

[Yann E. MORIN]

Thomas, All,

On 2014-03-05 17:24 +0100, Thomas De Schampheleire spake thusly:
> This patch adds a small section about working on items from the TODO list.
> 
> Signed-off-by: Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
> 
> ---
>  docs/manual/contribute.txt |  8 ++++++++
>  1 files changed, 8 insertions(+), 0 deletions(-)
> 
> diff --git a/docs/manual/contribute.txt b/docs/manual/contribute.txt
> --- a/docs/manual/contribute.txt
> +++ b/docs/manual/contribute.txt
> @@ -139,6 +139,14 @@ Buildroot's Patchwork website can be use
>  purposes. Please see xref:apply-patches-patchwork[] for more
>  information on using Buildroot's Patchwork website to apply patches.
>  
> +Work on items from the TODO list
> +--------------------------------
> +If you want to contribute to Buildroot but don't know where to start,

There should be an empty line below the '----' line. Even if asciidoc is
happy without one, it's not the way other chapters are written.

Regards,
Yann E. MORIN.

> +and you don't like any of the above topics, you can always work on items
> +from the http://elinux.org/Buildroot#Todo_list[Buildroot TODO list].
> +Don't hesitate to discuss an item first on the mailing list or on IRC.
> +Do edit the wiki to indicate when you start working on an item, so we
> +avoid duplicate efforts.
>  
>  [[submitting-patches]]
>  Submitting patches
> _______________________________________________
> buildroot mailing list
> buildroot at busybox.net
> http://lists.busybox.net/mailman/listinfo/buildroot

-- 
.-----------------.--------------------.------------------.--------------------.
|  Yann E. MORIN  | Real-Time Embedded | /"\ ASCII RIBBON | Erics' conspiracy: |
| +33 662 376 056 | Software  Designer | \ / CAMPAIGN     |  ___               |
| +33 223 225 172 `------------.-------:  X  AGAINST      |  \e/  There is no  |
| http://ymorin.is-a-geek.org/ | _/*\_ | / \ HTML MAIL    |   v   conspiracy.  |
'------------------------------^-------^------------------^--------------------'

[Buildroot] [PATCH 6 of 8] manual: contributing: minor rewording of 'submitting patches' section

[Thomas De Schampheleire]

This patch makes some minor changes to the section about submitting patches.
Content-wise there are little changes.

Signed-off-by: Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>

---
 docs/manual/contribute.txt |  20 +++++++++++---------
 1 files changed, 11 insertions(+), 9 deletions(-)

diff --git a/docs/manual/contribute.txt b/docs/manual/contribute.txt
--- a/docs/manual/contribute.txt
+++ b/docs/manual/contribute.txt
@@ -156,16 +156,18 @@ Submitting patches
 _Please, do not attach patches to bugs, send them to the mailing list
 instead_.
 
-When your changes are done, and committed in your local git view,
-_rebase_ your development branch on top of the upstream tree before
-generating the patch set. To do so, run:
+If you made some changes to Buildroot and you would like to contribute
+them to the Buildroot project, proceed as follows. Starting from the
+changes committed in your local git view, _rebase_ your development
+branch on top of the upstream tree before generating a patch set. To do
+so, run:
 
 ---------------------
 $ git fetch --all --tags
 $ git rebase origin/master
 ---------------------
 
-Here, you are ready to generate then submit your patch set.
+Now, you are ready to generate then submit your patch set.
 
 To generate it, run:
 
@@ -177,7 +179,7 @@ This will generate patch files in the +o
 automatically adding the +Signed-off-by+ line.
 
 Once patch files are generated, you can review/edit the commit message
-before submitting them using your favorite text editor.
+before submitting them, using your favorite text editor.
 
 Lastly, send/submit your patch set to the Buildroot mailing list:
 
@@ -188,9 +190,9 @@ Lastly, send/submit your patch set to th
 Note that +git+ should be configured to use your mail account.
 To configure +git+, see +man git-send-email+ or google it.
 
-Make sure posted *patches are not line-wrapped*, otherwise they cannot
-easily be applied. In such a case, fix your e-mail client, or better,
-use +git send-email+ to send your patches.
+If you do not use +git send-email+, make sure posted *patches are not
+line-wrapped*, otherwise they cannot easily be applied. In such a case,
+fix your e-mail client, or better yet, learn to use +git send-email+.
 
 Cover letter
 ~~~~~~~~~~~~
@@ -236,7 +238,7 @@ Hereafter the recommended layout:
 ---------------
 Patch title less than 80-character length
 
-Some more paragraph giving some more details.
+A paragraph giving more details.
 
 And yet another paragraph giving more details.
 

[Buildroot] [PATCH 6 of 8] manual: contributing: minor rewording of 'submitting patches' section

[Yann E. MORIN]

Thomas, All,

Not directly related to your patch...

On 2014-03-05 17:24 +0100, Thomas De Schampheleire spake thusly:
> @@ -236,7 +238,7 @@ Hereafter the recommended layout:
>  ---------------
>  Patch title less than 80-character length
>  
> -Some more paragraph giving some more details.
> +A paragraph giving more details.
>  
>  And yet another paragraph giving more details.

I like it when commit log are describing what the problem is, what the
reason is, and how it is solved. Something like:

    Patch title: short explanation, less than 80 chars

    A paragraph that explains the problem, and how
    it manifests itself. If the problem is complex,
    it is OK to add more paragraph.

    A paragraph that explains the root cause of the problem.
    Again, more than on paragraph is OK.

    Finally, a paragraph than explains how it is solved.
    
    Signed-off-by: John DOE <john.doe@example.net>

Regards,
Yann E. MORIN.

-- 
.-----------------.--------------------.------------------.--------------------.
|  Yann E. MORIN  | Real-Time Embedded | /"\ ASCII RIBBON | Erics' conspiracy: |
| +33 662 376 056 | Software  Designer | \ / CAMPAIGN     |  ___               |
| +33 223 225 172 `------------.-------:  X  AGAINST      |  \e/  There is no  |
| http://ymorin.is-a-geek.org/ | _/*\_ | / \ HTML MAIL    |   v   conspiracy.  |
'------------------------------^-------^------------------^--------------------'

[Buildroot] [PATCH 6 of 8] manual: contributing: minor rewording of 'submitting patches' section

[Arnout Vandecappelle]

On 05/03/14 18:26, Yann E. MORIN wrote:
> Thomas, All,
> 
> Not directly related to your patch...
> 
> On 2014-03-05 17:24 +0100, Thomas De Schampheleire spake thusly:
>> @@ -236,7 +238,7 @@ Hereafter the recommended layout:
>>  ---------------
>>  Patch title less than 80-character length
>>  
>> -Some more paragraph giving some more details.
>> +A paragraph giving more details.
>>  
>>  And yet another paragraph giving more details.
> 
> I like it when commit log are describing what the problem is, what the
> reason is, and how it is solved. Something like:
> 
>     Patch title: short explanation, less than 80 chars

 Actually, everything should be wrapped at 72 chars, since 'git log'
indents with a tab.


 Regards,
 Arnout

> 
>     A paragraph that explains the problem, and how
>     it manifests itself. If the problem is complex,
>     it is OK to add more paragraph.
> 
>     A paragraph that explains the root cause of the problem.
>     Again, more than on paragraph is OK.
> 
>     Finally, a paragraph than explains how it is solved.
>     
>     Signed-off-by: John DOE <john.doe@example.net>
> 
> Regards,
> Yann E. MORIN.
> 


-- 
Arnout Vandecappelle                          arnout at mind be
Senior Embedded Software Architect            +32-16-286500
Essensium/Mind                                http://www.mind.be
G.Geenslaan 9, 3001 Leuven, Belgium           BE 872 984 063 RPR Leuven
LinkedIn profile: http://www.linkedin.com/in/arnoutvandecappelle
GPG fingerprint:  7CB5 E4CC 6C2E EFD4 6E3D A754 F963 ECAB 2450 2F1F

[Buildroot] [PATCH 6 of 8] manual: contributing: minor rewording of 'submitting patches' section

[Yann E. MORIN]

Thomas, All,

On 2014-03-05 17:24 +0100, Thomas De Schampheleire spake thusly:
> This patch makes some minor changes to the section about submitting patches.
> Content-wise there are little changes.
> 
> Signed-off-by: Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>

Reviewed-by: "Yann E. MORIN" <yann.morin.1998@free.fr>

Regards,
Yann E. MORIN.

> ---
>  docs/manual/contribute.txt |  20 +++++++++++---------
>  1 files changed, 11 insertions(+), 9 deletions(-)
> 
> diff --git a/docs/manual/contribute.txt b/docs/manual/contribute.txt
> --- a/docs/manual/contribute.txt
> +++ b/docs/manual/contribute.txt
> @@ -156,16 +156,18 @@ Submitting patches
>  _Please, do not attach patches to bugs, send them to the mailing list
>  instead_.
>  
> -When your changes are done, and committed in your local git view,
> -_rebase_ your development branch on top of the upstream tree before
> -generating the patch set. To do so, run:
> +If you made some changes to Buildroot and you would like to contribute
> +them to the Buildroot project, proceed as follows. Starting from the
> +changes committed in your local git view, _rebase_ your development
> +branch on top of the upstream tree before generating a patch set. To do
> +so, run:
>  
>  ---------------------
>  $ git fetch --all --tags
>  $ git rebase origin/master
>  ---------------------
>  
> -Here, you are ready to generate then submit your patch set.
> +Now, you are ready to generate then submit your patch set.
>  
>  To generate it, run:
>  
> @@ -177,7 +179,7 @@ This will generate patch files in the +o
>  automatically adding the +Signed-off-by+ line.
>  
>  Once patch files are generated, you can review/edit the commit message
> -before submitting them using your favorite text editor.
> +before submitting them, using your favorite text editor.
>  
>  Lastly, send/submit your patch set to the Buildroot mailing list:
>  
> @@ -188,9 +190,9 @@ Lastly, send/submit your patch set to th
>  Note that +git+ should be configured to use your mail account.
>  To configure +git+, see +man git-send-email+ or google it.
>  
> -Make sure posted *patches are not line-wrapped*, otherwise they cannot
> -easily be applied. In such a case, fix your e-mail client, or better,
> -use +git send-email+ to send your patches.
> +If you do not use +git send-email+, make sure posted *patches are not
> +line-wrapped*, otherwise they cannot easily be applied. In such a case,
> +fix your e-mail client, or better yet, learn to use +git send-email+.
>  
>  Cover letter
>  ~~~~~~~~~~~~
> @@ -236,7 +238,7 @@ Hereafter the recommended layout:
>  ---------------
>  Patch title less than 80-character length
>  
> -Some more paragraph giving some more details.
> +A paragraph giving more details.
>  
>  And yet another paragraph giving more details.
>  
> _______________________________________________
> buildroot mailing list
> buildroot at busybox.net
> http://lists.busybox.net/mailman/listinfo/buildroot

-- 
.-----------------.--------------------.------------------.--------------------.
|  Yann E. MORIN  | Real-Time Embedded | /"\ ASCII RIBBON | Erics' conspiracy: |
| +33 662 376 056 | Software  Designer | \ / CAMPAIGN     |  ___               |
| +33 223 225 172 `------------.-------:  X  AGAINST      |  \e/  There is no  |
| http://ymorin.is-a-geek.org/ | _/*\_ | / \ HTML MAIL    |   v   conspiracy.  |
'------------------------------^-------^------------------^--------------------'

[Buildroot] [PATCH 6 of 8] manual: contributing: minor rewording of 'submitting patches' section

[Samuel Martin]

On Wed, Mar 5, 2014 at 6:29 PM, Yann E. MORIN <yann.morin.1998@free.fr> wrote:
> Thomas, All,
>
> On 2014-03-05 17:24 +0100, Thomas De Schampheleire spake thusly:
>> This patch makes some minor changes to the section about submitting patches.
>> Content-wise there are little changes.
>>
>> Signed-off-by: Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
>
> Reviewed-by: "Yann E. MORIN" <yann.morin.1998@free.fr>

Acked-by: Samuel Martin <s.martin49@gmail.com>

Regards,

-- 
Samuel

[Buildroot] [PATCH 7 of 8] manual: contributing: don't recommend leaving out changelog from patches

[Thomas De Schampheleire]

Currently, the manual states that if you send a series and include a
changelog in the introduction mail (0 of x), it is not necessary to include
a changelog on the individual patches.
I don't like this: for large patch series it requires going back to the
introduction mail when opening each patch, to understand what changed.
This patch rewords the paragraph accordingly.

Signed-off-by: Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>

---
 docs/manual/contribute.txt |  4 ++--
 1 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/docs/manual/contribute.txt b/docs/manual/contribute.txt
--- a/docs/manual/contribute.txt
+++ b/docs/manual/contribute.txt
@@ -220,8 +220,8 @@ Patch revision changelog
 When improvements are requested, the new revision of each commit
 should include a changelog of the modifications between each
 submission. Note that when your patch series is introduced by a cover
-letter, the changelog may be added in the cover letter rather than in
-the individual commits.
+letter, an overall changelog may be added to the cover letter in
+addition to the changelog in the individual commits.
 
 When added to the individual commits, this changelog is added when
 editing the commit message.  Below the +Signed-off-by+ section, add

[Buildroot] [PATCH 7 of 8] manual: contributing: don't recommend leaving out changelog from patches

[Yann E. MORIN]

Thomas, All,

On 2014-03-05 17:24 +0100, Thomas De Schampheleire spake thusly:
> Currently, the manual states that if you send a series and include a
> changelog in the introduction mail (0 of x), it is not necessary to include
> a changelog on the individual patches.

> I don't like this: for large patch series it requires going back to the
> introduction mail when opening each patch, to understand what changed.
> This patch rewords the paragraph accordingly.

Maybe the "I don't like this" should not be part of the actual commit
log. The rest of the paragraph is OK, however.

Globally, I agree. I don't usually keep per-patch changelogs, but then I
can have a hard time writing the global changelog in the cover-letter.
Keeping a per-patch changelog (updated with each git commit --amend)
would greatly help write the global one.

Regards,
Yann E. MORIN.

> Signed-off-by: Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
> 
> ---
>  docs/manual/contribute.txt |  4 ++--
>  1 files changed, 2 insertions(+), 2 deletions(-)
> 
> diff --git a/docs/manual/contribute.txt b/docs/manual/contribute.txt
> --- a/docs/manual/contribute.txt
> +++ b/docs/manual/contribute.txt
> @@ -220,8 +220,8 @@ Patch revision changelog
>  When improvements are requested, the new revision of each commit
>  should include a changelog of the modifications between each
>  submission. Note that when your patch series is introduced by a cover
> -letter, the changelog may be added in the cover letter rather than in
> -the individual commits.
> +letter, an overall changelog may be added to the cover letter in
> +addition to the changelog in the individual commits.
>  
>  When added to the individual commits, this changelog is added when
>  editing the commit message.  Below the +Signed-off-by+ section, add
> _______________________________________________
> buildroot mailing list
> buildroot at busybox.net
> http://lists.busybox.net/mailman/listinfo/buildroot

-- 
.-----------------.--------------------.------------------.--------------------.
|  Yann E. MORIN  | Real-Time Embedded | /"\ ASCII RIBBON | Erics' conspiracy: |
| +33 662 376 056 | Software  Designer | \ / CAMPAIGN     |  ___               |
| +33 223 225 172 `------------.-------:  X  AGAINST      |  \e/  There is no  |
| http://ymorin.is-a-geek.org/ | _/*\_ | / \ HTML MAIL    |   v   conspiracy.  |
'------------------------------^-------^------------------^--------------------'

[Buildroot] [PATCH 8 of 8] manual: contributing: minor rewording of 'reporting bugs' section

[Thomas De Schampheleire]

This patch makes some minor fixes in the section about reporting bugs.

Signed-off-by: Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>

---
 docs/manual/contribute.txt |  15 ++++++++-------
 1 files changed, 8 insertions(+), 7 deletions(-)

Although I don't think this section belongs in the Contributing chapter,
there currently isn't a better place. When I get to rethinking the manual
structure, this can be changed.

diff --git a/docs/manual/contribute.txt b/docs/manual/contribute.txt
--- a/docs/manual/contribute.txt
+++ b/docs/manual/contribute.txt
@@ -266,16 +266,16 @@ This can be easily handled with +git for
 ---------------------
 
 [[reporting-bugs]]
-Reporting issues/bugs, get help
--------------------------------
+Reporting issues/bugs or getting help
+-------------------------------------
 
 Before reporting any issue, please check
 xref:mailing-list-subscribe[the mailing list archive] in case someone has
 already reported and fixed a similar problem.
 
-However you choose to report bugs or get help,
-xref:bugtracker[opening a bug] or
-xref:mailing-list-subscribe[send a mail to the mailing list], there are
+However you choose to report bugs or get help, either by
+xref:bugtracker[opening a bug] or by
+xref:mailing-list-subscribe[sending a mail to the mailing list], there are
 a number of details to provide in order to help people reproduce and
 find a solution to the issue.
 
@@ -287,11 +287,12 @@ Here is a short list of details to provi
 * host machine (OS/release)
 * version of Buildroot
 * target for which the build fails
-* package(s) which the build fails
+* package(s) for which the build fails
 * the command that fails and its output
 * any information you think that may be relevant
 
-Additionnally, your can add the +.config+ file.
+Additionally, you should add the +.config+ file (or if you know how, a
++defconfig+).
 
 If some of these details are too large, do not hesitate to use a
 pastebin service (see http://www.similarsitesearch.com/alternatives-to/pastebin.com[]).

[Buildroot] [PATCH 8 of 8] manual: contributing: minor rewording of 'reporting bugs' section

[Yann E. MORIN]

Thomas, All,

On 2014-03-05 17:24 +0100, Thomas De Schampheleire spake thusly:
> This patch makes some minor fixes in the section about reporting bugs.
> 
> Signed-off-by: Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
> 
> ---
>  docs/manual/contribute.txt |  15 ++++++++-------
>  1 files changed, 8 insertions(+), 7 deletions(-)
> 
> Although I don't think this section belongs in the Contributing chapter,
> there currently isn't a better place. When I get to rethinking the manual
> structure, this can be changed.
> 
> diff --git a/docs/manual/contribute.txt b/docs/manual/contribute.txt
> --- a/docs/manual/contribute.txt
> +++ b/docs/manual/contribute.txt
> @@ -266,16 +266,16 @@ This can be easily handled with +git for
>  ---------------------
>  
>  [[reporting-bugs]]
> -Reporting issues/bugs, get help
> --------------------------------
> +Reporting issues/bugs or getting help
> +-------------------------------------
>  
>  Before reporting any issue, please check
>  xref:mailing-list-subscribe[the mailing list archive] in case someone has
>  already reported and fixed a similar problem.
>  
> -However you choose to report bugs or get help,
> -xref:bugtracker[opening a bug] or
> -xref:mailing-list-subscribe[send a mail to the mailing list], there are
> +However you choose to report bugs or get help, either by
> +xref:bugtracker[opening a bug] or by
> +xref:mailing-list-subscribe[sending a mail to the mailing list], there are
>  a number of details to provide in order to help people reproduce and
>  find a solution to the issue.
>  
> @@ -287,11 +287,12 @@ Here is a short list of details to provi
>  * host machine (OS/release)
>  * version of Buildroot
>  * target for which the build fails
> -* package(s) which the build fails
> +* package(s) for which the build fails
>  * the command that fails and its output
>  * any information you think that may be relevant
>  
> -Additionnally, your can add the +.config+ file.
> +Additionally, you should add the +.config+ file (or if you know how, a
> ++defconfig+).

... the +.config+ file (or better yet, a +defconfig+)

>  If some of these details are too large, do not hesitate to use a
>  pastebin service (see http://www.similarsitesearch.com/alternatives-to/pastebin.com[]).

There are some pastebin sites which, when you download the 'raw' paste,
will send you a CRLF file. This is inconvenient, since the files have to
be converted first. Maybe we could list a pastebins that don;t do that,
and list them prominently?

Regards,
Yann E. MORIN.

-- 
.-----------------.--------------------.------------------.--------------------.
|  Yann E. MORIN  | Real-Time Embedded | /"\ ASCII RIBBON | Erics' conspiracy: |
| +33 662 376 056 | Software  Designer | \ / CAMPAIGN     |  ___               |
| +33 223 225 172 `------------.-------:  X  AGAINST      |  \e/  There is no  |
| http://ymorin.is-a-geek.org/ | _/*\_ | / \ HTML MAIL    |   v   conspiracy.  |
'------------------------------^-------^------------------^--------------------'

[Buildroot] [PATCH 8 of 8] manual: contributing: minor rewording of 'reporting bugs' section

[Samuel Martin]

Hi Thomas,

On Wed, Mar 5, 2014 at 5:24 PM, Thomas De Schampheleire
<patrickdepinguin@gmail.com> wrote:
> This patch makes some minor fixes in the section about reporting bugs.
>
> Signed-off-by: Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
>
> ---
>  docs/manual/contribute.txt |  15 ++++++++-------
>  1 files changed, 8 insertions(+), 7 deletions(-)
>
> Although I don't think this section belongs in the Contributing chapter,
> there currently isn't a better place. When I get to rethinking the manual
> structure, this can be changed.
>
> diff --git a/docs/manual/contribute.txt b/docs/manual/contribute.txt
> --- a/docs/manual/contribute.txt
> +++ b/docs/manual/contribute.txt
> @@ -266,16 +266,16 @@ This can be easily handled with +git for
>  ---------------------
>
>  [[reporting-bugs]]
> -Reporting issues/bugs, get help
> --------------------------------
> +Reporting issues/bugs or getting help
> +-------------------------------------
>
>  Before reporting any issue, please check
>  xref:mailing-list-subscribe[the mailing list archive] in case someone has

We could add a link to buildroot gmane. This iscertainly the easiest
way to search the ML archive.

>  already reported and fixed a similar problem.
>
> -However you choose to report bugs or get help,
> -xref:bugtracker[opening a bug] or
> -xref:mailing-list-subscribe[send a mail to the mailing list], there are
> +However you choose to report bugs or get help, either by
> +xref:bugtracker[opening a bug] or by
> +xref:mailing-list-subscribe[sending a mail to the mailing list], there are
>  a number of details to provide in order to help people reproduce and
>  find a solution to the issue.
>
> @@ -287,11 +287,12 @@ Here is a short list of details to provi
>  * host machine (OS/release)
>  * version of Buildroot
>  * target for which the build fails
> -* package(s) which the build fails
> +* package(s) for which the build fails
>  * the command that fails and its output
>  * any information you think that may be relevant
>
> -Additionnally, your can add the +.config+ file.
> +Additionally, you should add the +.config+ file (or if you know how, a
> ++defconfig+).
>
>  If some of these details are too large, do not hesitate to use a
>  pastebin service (see http://www.similarsitesearch.com/alternatives-to/pastebin.com[]).
> _______________________________________________
> buildroot mailing list
> buildroot at busybox.net
> http://lists.busybox.net/mailman/listinfo/buildroot

Regards,

-- 
Samuel

[Buildroot] [PATCH 8 of 8] manual: contributing: minor rewording of 'reporting bugs' section

[Thomas De Schampheleire]

Hi Samuel,

On Wed, Mar 5, 2014 at 10:05 PM, Samuel Martin <s.martin49@gmail.com> wrote:
> Hi Thomas,
>
> On Wed, Mar 5, 2014 at 5:24 PM, Thomas De Schampheleire
> <patrickdepinguin@gmail.com> wrote:
>> This patch makes some minor fixes in the section about reporting bugs.
>>
>> Signed-off-by: Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
>>
>> ---
>>  docs/manual/contribute.txt |  15 ++++++++-------
>>  1 files changed, 8 insertions(+), 7 deletions(-)
>>
>> Although I don't think this section belongs in the Contributing chapter,
>> there currently isn't a better place. When I get to rethinking the manual
>> structure, this can be changed.
>>
>> diff --git a/docs/manual/contribute.txt b/docs/manual/contribute.txt
>> --- a/docs/manual/contribute.txt
>> +++ b/docs/manual/contribute.txt
>> @@ -266,16 +266,16 @@ This can be easily handled with +git for
>>  ---------------------
>>
>>  [[reporting-bugs]]
>> -Reporting issues/bugs, get help
>> --------------------------------
>> +Reporting issues/bugs or getting help
>> +-------------------------------------
>>
>>  Before reporting any issue, please check
>>  xref:mailing-list-subscribe[the mailing list archive] in case someone has
>
> We could add a link to buildroot gmane. This iscertainly the easiest
> way to search the ML archive.
>

This link is already present from the 'the mailing list archive'
reference, so I don't think we should replicate it here, right?

thanks,
Thomas

[Buildroot] [PATCH 8 of 8] manual: contributing: minor rewording of 'reporting bugs' section

[Samuel Martin]

On Thu, Mar 6, 2014 at 9:55 AM, Thomas De Schampheleire
<patrickdepinguin@gmail.com> wrote:
> Hi Samuel,
>
> On Wed, Mar 5, 2014 at 10:05 PM, Samuel Martin <s.martin49@gmail.com> wrote:
>> Hi Thomas,
>>
>> On Wed, Mar 5, 2014 at 5:24 PM, Thomas De Schampheleire
>> <patrickdepinguin@gmail.com> wrote:
>>> This patch makes some minor fixes in the section about reporting bugs.
>>>
>>> Signed-off-by: Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
>>>
>>> ---
>>>  docs/manual/contribute.txt |  15 ++++++++-------
>>>  1 files changed, 8 insertions(+), 7 deletions(-)
>>>
>>> Although I don't think this section belongs in the Contributing chapter,
>>> there currently isn't a better place. When I get to rethinking the manual
>>> structure, this can be changed.
>>>
>>> diff --git a/docs/manual/contribute.txt b/docs/manual/contribute.txt
>>> --- a/docs/manual/contribute.txt
>>> +++ b/docs/manual/contribute.txt
>>> @@ -266,16 +266,16 @@ This can be easily handled with +git for
>>>  ---------------------
>>>
>>>  [[reporting-bugs]]
>>> -Reporting issues/bugs, get help
>>> --------------------------------
>>> +Reporting issues/bugs or getting help
>>> +-------------------------------------
>>>
>>>  Before reporting any issue, please check
>>>  xref:mailing-list-subscribe[the mailing list archive] in case someone has
>>
>> We could add a link to buildroot gmane. This iscertainly the easiest
>> way to search the ML archive.
>>
>
> This link is already present from the 'the mailing list archive'
> reference, so I don't think we should replicate it here, right?

Fair enough!

>
> thanks,
> Thomas

Regards,

-- 
Samuel

[Buildroot] [PATCH 0 of 8] manual: rework Contributing chapter

[Thomas Petazzoni]

Dear Thomas De Schampheleire,

On Wed, 05 Mar 2014 17:24:26 +0100, Thomas De Schampheleire wrote:

> This patch series reworks the "Contributing to Buildroot" chapter in the
> manual. According to the latest Buildroot Developer Days, we want to promote
> contributions that are not feature patches, like fixing autobuild failures,
> closing bugs, working on items from the TODO list, etc. This series reorders
> and expands the chapter with that desire in mind.
> 
> Signed-off-by: Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
> 
> ---
>  docs/manual/contribute.txt |  334 ++++++++++++++++++++++++----------------
>  1 files changed, 196 insertions(+), 138 deletions(-)

I've applied patches 1 and 2. For the other patches, Yann has made some
comments.

Thomas
-- 
Thomas Petazzoni, CTO, Free Electrons
Embedded Linux, Kernel and Android engineering
http://free-electrons.com