[Buildroot] [PATCH v3 0/3] Manual updates

[Buildroot] [PATCH v3 0/3] Manual updates

[Samuel Martin]

All,

Here is a couple of various manual updates and fixes.

The noticeable change from the 2nd round is the removal of the
"Beyond Buildroot" additions since it needs more thoughts and work
about it.

Regards,

Samuel

--

A.R.D (1):
  manual: tips: document how to build the manual

Samuel Martin (1):
  manual: minor typos and formating fixes

Vinicius Tinti (1):
  manual: contribute.txt: add patch revision section

 docs/manual/adding-packages-generic.txt | 16 ++++---
 docs/manual/contribute.txt              | 78 +++++++++++++++++++++++++++++----
 docs/manual/make-tips.txt               | 25 +++++++++--
 3 files changed, 103 insertions(+), 16 deletions(-)

--
1.8.3.4

[Buildroot] [PATCH v3 1/3] manual: contribute.txt: add patch revision section

[Samuel Martin]

From: Vinicius Tinti <viniciustinti@gmail.com>

Improve the contribute manual section by adding an explanation about patch
review and version.

The section now provides advices in how to respond maintainers requests and how
to proceed on replying them.

Signed-off-by: Vinicius Tinti <viniciustinti@gmail.com>
Signed-off-by: Samuel Martin <s.martin49@gmail.com>

---
changes v2 -> v3:
(fixes and rewordings suggested or spotted by Thomas P. and Thomas De S.)
- add "Cover letter" section
- reword "Patch revision changelog" section
- remove "Keeping patch revision in the same thread" section
- update commit message

changes v1 -> v2:
- minor rewordings + misc. formating fixes
---
 docs/manual/contribute.txt | 70 +++++++++++++++++++++++++++++++++++++++++++---
 1 file changed, 66 insertions(+), 4 deletions(-)

diff --git a/docs/manual/contribute.txt b/docs/manual/contribute.txt
index 0106df0..9f3b641 100644
--- a/docs/manual/contribute.txt
+++ b/docs/manual/contribute.txt
@@ -42,10 +42,6 @@ To generate it, run:
 This will generate patch files in the +outgoing+ subdirectory,
 automatically adding the +signed-off-by+ line.
 
-If you want to present the whole patch set in a separate mail, add
-+--cover-letter+ to the previous command line (+man git-format-patch+
-for further information).
-
 Once patch files are generated, you can review/edit the commit message
 before submitting them using your favorite text editor.
 
@@ -62,6 +58,72 @@ 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.
 
+Cover letter
+~~~~~~~~~~~~
+
+If you want to present the whole patch set in a separate mail, add
++--cover-letter+ to the +git format-patch+ command
+(see +man git-format-patch+ for further information).
+
+A 'cover letter' may be useful to introduce the changes you propose
+in the following cases:
+
+* large number of commits in the series;
+
+* deep impact of the changes in the rest of the project;
+
+* RFC footnote:[RFC: (Request for comments) change proposal];
+
+* whenever you feel it will help presenting your work, your choices,
+  the review process, etc.
+
+Patch revision changelog
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+When improvements are requested, the new revision of the each commit
+should include a changelog of the modifications between each submission.
+
+This changelog is added when editing the commit message.
+Below the +Signed-off-by+ section, add +---+ and your changelog.
+
+Although the changelog will be visible for the reviewers in the mail
+thread, as well as in http://patchwork.buildroot.org[patchwork], +git+
+will automatically ignores lines below +---+ when the patch will be
+merged.
+
+Hereafter the recommended layout:
+
+---------------
+Patch title less than 80-character length
+
+Some more paragraph giving some more details.
+
+And yet another paragraph giving more details.
+
+Signed-off-by John Doe <john.doe@noname.org>
+
+---
+Changes v2 -> v3:
+  - foo bar  (suggested by Jane)
+  - bar buz
+
+Changes v1 -> v2:
+  - alpha bravo  (suggested by John)
+  - charly delta
+---------------
+
+Any patch revision should include the version number. The version number
+is simply composed of the letter +v+ followed by an +integer+ greater or
+equal to two (i.e. "PATCH v2", "PATCH v3" ...).
+
+This can be easily handled with +git format-patch+ by using the option
++--subject-prefix+:
+
+---------------------
+$ git format-patch --subject-prefix "PATCH v4" \
+    -M -o outgoing origin/master
+---------------------
+
 Reviewing/Testing patches
 -------------------------
 
-- 
1.8.3.4

[Buildroot] [PATCH v3 2/3] manual: tips: document how to build the manual

[Samuel Martin]

From: "A.R.D" <contact@team-ard.com>

Signed-off-by: A.R.D. <contact@team-ard.com>
Cc: Willy Lambert <lambert.willy@gmail.com>
Signed-off-by: Samuel Martin <s.martin49@gmail.com>

changes v2 -> v3:
- typos (spotted by Thomas De S.)
- add cross-refs
- update commit message
---
 docs/manual/make-tips.txt | 17 +++++++++++++++++
 1 file changed, 17 insertions(+)

diff --git a/docs/manual/make-tips.txt b/docs/manual/make-tips.txt
index b4a9c12..e87bbf7 100644
--- a/docs/manual/make-tips.txt
+++ b/docs/manual/make-tips.txt
@@ -54,6 +54,23 @@ and target trees, the images and the toolchain):
  $ make clean
 --------------------
 
+.Generating the manual:
+
+The present manual sources are located in the 'docs/manual' directory.
+To generate the manual:
+
+---------------------------------
+ $ make manual-clean
+ $ make manual
+---------------------------------
+
+The manual outputs will be generated in 'output/docs/manual'.
+
+.Notes
+- +asciidoc+ is required to build the documentation (see:
+  xref:requirement-optional[]).
+- There is a known issue that you can't build it under Debian Squeeze.
+
 To delete all build products as well as the configuration:
 
 --------------------
-- 
1.8.3.4

[Buildroot] [PATCH v3 3/3] manual: minor typos and formating fixes

[Samuel Martin]

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

---
changes v2 -> v3:
- fix typos (spotted by Thomas De S.)
- more typos and formating fixes
---
 docs/manual/adding-packages-generic.txt | 16 +++++++++++-----
 docs/manual/contribute.txt              |  8 ++++----
 docs/manual/make-tips.txt               |  8 +++++---
 3 files changed, 20 insertions(+), 12 deletions(-)

diff --git a/docs/manual/adding-packages-generic.txt b/docs/manual/adding-packages-generic.txt
index fdca612..4e50f8f 100644
--- a/docs/manual/adding-packages-generic.txt
+++ b/docs/manual/adding-packages-generic.txt
@@ -99,24 +99,30 @@ of the shell script(s) needing fixing. All these names are relative to
 In addition, the scripts listed in +LIBFOO_CONFIG_SCRIPTS+ are removed
 from +$(TARGET_DIR)/usr/bin+, since they are not needed on the target.
 
-Example 1:
-
+.Config script: 'divine' package
+================================
 Package divine installs shell script '$(STAGING_DIR)/usr/bin/divine-config'.
 
-So it's fixup would be:
+So its fixup would be:
 
+--------------------------------
 DIVINE_CONFIG_SCRIPTS = divine-config
+--------------------------------
+================================
 
-Example 2:
-
+.Config script: 'imagemagick' package:
+================================
 Package imagemagick installs the following scripts:
 '$(STAGING_DIR)/usr/bin/{Magick,Magick++,MagickCore,MagickWand,Wand}-config'
 
 So it's fixup would be:
 
+--------------------------------
 IMAGEMAGICK_CONFIG_SCRIPTS = \
    Magick-config Magick++-config \
    MagickCore-config MagickWand-config Wand-config
+--------------------------------
+================================
 
 On line 14, we specify the list of dependencies this package relies
 on. These dependencies are listed in terms of lower-case package names,
diff --git a/docs/manual/contribute.txt b/docs/manual/contribute.txt
index 9f3b641..46a4489 100644
--- a/docs/manual/contribute.txt
+++ b/docs/manual/contribute.txt
@@ -27,8 +27,8 @@ _rebase_ your development branch on top of the upstream tree before
 generating the patch set. To do so, run:
 
 ---------------------
- $ git fetch --all --tags
- $ git rebase origin/master
+$ git fetch --all --tags
+$ git rebase origin/master
 ---------------------
 
 Here, you are ready to generate then submit your patch set.
@@ -36,7 +36,7 @@ Here, you are ready to generate then submit your patch set.
 To generate it, run:
 
 ---------------------
- $ git format-patch -M -n -s -o outgoing origin/master
+$ git format-patch -M -n -s -o outgoing origin/master
 ---------------------
 
 This will generate patch files in the +outgoing+ subdirectory,
@@ -48,7 +48,7 @@ before submitting them using your favorite text editor.
 Lastly, send/submit your patch set to the Buildroot mailing list:
 
 ---------------------
- $ git send-email --to buildroot at busybox.net outgoing/*
+$ git send-email --to buildroot at busybox.net outgoing/*
 ---------------------
 
 Note that +git+ should be configured to use your mail account.
diff --git a/docs/manual/make-tips.txt b/docs/manual/make-tips.txt
index e87bbf7..c3fd155 100644
--- a/docs/manual/make-tips.txt
+++ b/docs/manual/make-tips.txt
@@ -29,8 +29,7 @@ The result of the search shows the help message of the matching items.
  $ make help
 --------------------
 
-.Not all targets are always available,
-
+Not all targets are always available,
 some settings in the +.config+ file may hide some targets:
 
 * +linux-menuconfig+ and +linux-savedefconfig+ only work when
@@ -71,12 +70,15 @@ The manual outputs will be generated in 'output/docs/manual'.
   xref:requirement-optional[]).
 - There is a known issue that you can't build it under Debian Squeeze.
 
+.Reseting Buildroot for a new target:
+
 To delete all build products as well as the configuration:
 
 --------------------
  $ make distclean
 --------------------
 
-Note that if +ccache+ is enabled, running +make clean+ or +distclean+ does
+.Notes
+If +ccache+ is enabled, running +make clean+ or +distclean+ does
 not empty the compiler cache used by Buildroot. To delete it, refer
 to xref:ccache[].
-- 
1.8.3.4

[Buildroot] [PATCH v3 0/3] Manual updates

[Thomas Petazzoni]

Dear Samuel Martin,

On Fri,  9 Aug 2013 12:16:45 +0200, Samuel Martin wrote:

> Here is a couple of various manual updates and fixes.
> 
> The noticeable change from the 2nd round is the removal of the
> "Beyond Buildroot" additions since it needs more thoughts and work
> about it.

Committed, thanks.

Thomas
-- 
Thomas Petazzoni, Free Electrons
Kernel, drivers, real-time and embedded Linux
development, consulting, training and support.
http://free-electrons.com