docs/manual: add new section about the DEVELOPERS file and get-developer

[Peter: tweak wording and add xref as suggested by Arnout]
Signed-off-by: Thomas Petazzoni <thomas.petazzoni@free-electrons.com>
Signed-off-by: Peter Korsgaard <peter@korsgaard.com>

diff --git a/docs/manual/contribute.txt b/docs/manual/contribute.txt
index d4ec2e11846c288f68d6ffa515c21f7dd4ab2e16..c2c8a90170b7775a6789cac7a600fc43d70e5841 100644 (file)
--- a/docs/manual/contribute.txt
+++ b/docs/manual/contribute.txt
@@ -258,6 +258,12 @@ removed, preferably with the upstream commit ID. Also any other
 required changes should be explained explicitly, like configure
 options that no longer exist or are no longer needed.
 
+If you are interested in getting notified of build failures and of
+further changes in the packages you added or modified, please add
+yourself to the DEVELOPERS file. This should be done in a separate
+patch of the series. See xref:DEVELOPERS[the DEVELOPERS file] for more
+information.
+
 ==== Preparing a patch series
 
 Starting from the changes committed in your local git view, _rebase_
@@ -284,8 +290,9 @@ Once patch files are generated, you can review/edit the commit message
 before submitting them, using your favorite text editor.
 
 Buildroot provides a handy tool to know to whom your patches should be
-sent, called +get-developers+. This tool reads your patches and
-outputs the appropriate +git send-email+ command to use:
+sent, called +get-developers+ (see xref:DEVELOPERS[] for more
+information). This tool reads your patches and outputs the appropriate
++git send-email+ command to use:
 
 ---------------------
 $ ./support/scripts/get-developers outgoing/*

diff --git a/docs/manual/developers.txt b/docs/manual/developers.txt
new file mode 100644 (file)
index 0000000..ea1f894
--- /dev/null
+++ b/docs/manual/developers.txt
@@ -0,0 +1,46 @@
+// -*- mode:doc; -*-
+// vim: set syntax=asciidoc:
+
+[[DEVELOPERS]]
+== DEVELOPERS file and get-developers
+
+The main Buildroot directory contains a file named +DEVELOPERS+ that
+list the developers involved with various areas of Buildroot. Thanks to
+this file, the +get-developer+ tool allows to:
+
+- Calculate the list of developers to whom patches should be sent, by
+  parsing the patches and matching the modified files with the
+  relevant developers. See xref:submitting-patches[] for details.
+
+- Find which developers are taking care of a given architecture or
+  package, so that they can be notified when a build failure occurs on
+  this architecture or package. This is done in interaction with
+  Buildroot's autobuild infrastructure.
+
+We ask developers adding new packages, new boards, or generally new
+functionality in Buildroot, to register themselves in the +DEVELOPERS+
+file. As an example, we expect a developer contributing a new package
+to include in his patch the appropriate modification to the
++DEVELOPERS+ file.
+
+The +DEVELOPERS+ file format is documented in detail inside the file
+itself.
+
+The +get-developer+ tool, located in +support/scripts+ allows to use
+the +DEVELOPERS+ file for various tasks:
+
+- When passing one or several patches as command line argument,
+  +get-developer+ will return the appropriate +git send-email+
+  command.
+
+- When using the +-a <arch>+ command line option, +get-developer+ will
+  return the list of developers in charge of the given architecture.
+
+- When using the +-p <package>+ command line option, +get-developer+
+  will return the list of developers in charge of the given package.
+
+- When using the +-c+ command line option, +get-developer+ will look
+  at all files under version control in the Buildroot repository, and
+  list the ones that are not handled by any developer. The purpose of
+  this option is to help completing the +DEVELOPERS+ file.
+

diff --git a/docs/manual/manual.txt b/docs/manual/manual.txt
index 3c531e3738f7376511e77934c31fe355951dcea4..7630ea6c72e628308e06c7bf0ed68f6eca11d2a3 100644 (file)
--- a/docs/manual/manual.txt
+++ b/docs/manual/manual.txt
@@ -64,6 +64,8 @@ include::debugging-buildroot.txt[]
 
 include::contribute.txt[]
 
+include::developers.txt[]
+
 = Appendix
 
 include::appendix.txt[]