manual: rework Contributing chapter

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 <[email protected]>

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

docs/manual/contribute.txt +20 -11

@@ -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

Thomas, All,

On 2014-03-05 17:24 +0100, Thomas De Schampheleire spake thusly:

Quoted 6 lines

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 <[email protected]>

Reviewed-by "Yann E. MORIN" <[email protected]>

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

Signed-off-by Thomas De Schampheleire <[email protected]>

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

docs/manual/contribute.txt +10 -0

@@ -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

Thomas, All,

On 2014-03-05 17:24 +0100, Thomas De Schampheleire spake thusly:

Quoted 4 lines

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

Signed-off-by Thomas De Schampheleire <[email protected]>

Reviewed-by "Yann E. MORIN" <[email protected]>

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.

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 <[email protected]>

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

docs/manual/contribute.txt +65 -62

@@ -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

Thomas, All,

On 2014-03-05 17:24 +0100, Thomas De Schampheleire spake thusly:

Quoted 6 lines

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 <[email protected]>

Reviewed-by "Yann E. MORIN" <[email protected]>

Regards,
Yann E. MORIN.

Quoted 42 lines

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

docs/manual/contribute.txt +31 -0

@@ -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.

docs/manual/contribute.txt basically two things that can be done: · line 116

Quoted 8 lines

docs/manual/contribute.txt +8 -0

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

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 <[email protected]>

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

docs/manual/contribute.txt +0 -0

@@ -75,6 +75,71 @@ basically two things that can be done:
 Fixes http://autobuild.buildroot.org/results/51000a9d4656afe9e0ea6f07b9f8ed374c2e4069

docs/manual/contribute.txt +46 -62

+  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

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

Signed-off-by Thomas De Schampheleire <[email protected]>

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

docs/manual/contribute.txt +5 -0

+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

Thomas, All,

Not directly related to your patch...

On 2014-03-05 17:24 +0100, Thomas De Schampheleire spake thusly:

Quoted 7 lines

docs/manual/contribute.txt +1 -1

@@ -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.
 

docs/manual/contribute.txt Hereafter the recommended layout: · line 243

Quoted 1 line

docs/manual/contribute.txt +0 -0

 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 <[email protected]>

Regards,
Yann E. MORIN.

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

Signed-off-by Thomas De Schampheleire <[email protected]>

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

docs/manual/contribute.txt +11 -9

@@ -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

Thomas, All,

On 2014-03-05 17:24 +0100, Thomas De Schampheleire spake thusly:

Quoted 4 lines

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

Signed-off-by Thomas De Schampheleire <[email protected]>

Reviewed-by "Yann E. MORIN" <[email protected]>

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 <[email protected]>

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

docs/manual/contribute.txt +2 -2

@@ -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

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

Signed-off-by Thomas De Schampheleire <[email protected]>

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

docs/manual/contribute.txt +5 -5

@@ -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)

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

Signed-off-by Thomas De Schampheleire <[email protected]>

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

docs/manual/contribute.txt +6 -5

 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

Hi Thomas,

Quoted 24 lines · Thomas De Schampheleire

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

Signed-off-by Thomas De Schampheleire <[email protected]>

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

docs/manual/contribute.txt +2 -2

@@ -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
+-------------------------------------
 

docs/manual/contribute.txt This can be easily handled with +git for · line 273

Quoted 2 lines

docs/manual/contribute.txt +0 -0

 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.

Hi Samuel,

Quoted 28 lines · Samuel Martin

Hi Thomas,

Quoted 24 lines · Thomas De Schampheleire

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

Signed-off-by Thomas De Schampheleire <[email protected]>

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

docs/manual/contribute.txt +2 -2

@@ -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
+-------------------------------------
 

Quoted 6 lines

docs/manual/contribute.txt This can be easily handled with +git for · line 273

Quoted 2 lines

docs/manual/contribute.txt +0 -0

 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

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 <[email protected]>

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