3 files changed, 101 insertions, 8 deletions
diff --git a/docs/manual/contribute.txt b/docs/manual/contribute.txt
index b74897d28b..1b1f4de196 100644
--- a/docs/manual/contribute.txt
+++ b/docs/manual/contribute.txt
@@ -182,10 +182,87 @@ _Please, do not attach patches to bugs, send them to the mailing list
 instead_.
 
 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:
+them to the Buildroot project, proceed as follows.
+
+==== The formatting of a patch
+
+We expect patches to be formatted in a specific way. This is necessary
+to make it easy to review patches, to be able to apply them easily to
+the git repository, to make it easy to find back in the history how
+and why things have changed, and to make it possible to use +git
+bisect+ to locate the origin of a problem.
+
+First of all, it is essential that the patch has a good commit
+message. The commit message should start with a separate line with a
+brief summary of the change, starting with the name of the affected
+package. The body of the commit message should describe _why_ this
+change is needed, and if necessary also give details about _how_ it
+was done. When writing the commit message, think of how the reviewers
+will read it, but also think about how you will read it when you look
+at this change again a few years down the line.
+
+Second, the patch itself should do only one change, but do it
+completely. Two unrelated or weakly related changes should usually be
+done in two separate patches. This usually means that a patch affects
+only a single package. If several changes are related, it is often
+still possible to split them up in small patches and apply them in a
+specific order. Small patches make it easier to review, and often
+make it easier to understand afterwards why a change was done.
+However, each patch must be complete. It is not allowed that the
+build is broken when only the first but not the second patch is
+applied. This is necessary to be able to use +git bisect+ afterwards.
+
+Of course, while you're doing your development, you're probably going
+back and forth between packages, and certainly not committing things
+immediately in a way that is clean enough for submission. So most
+developers rewrite the history of commits to produce a clean set of
+commits that is appropriate for submission. To do this, you need to
+use _interactive rebasing_. You can learn about it
+https://git-scm.com/book/en/v2/Git-Tools-Rewriting-History[in the Pro
+Git book]. Sometimes, it is even easier to discard you history with
++git reset --soft origin/master+ and select individual changes with
++git add -i+ or +git add -p+.
+
+Finally, the patch should be signed off. This is done by adding
++Signed-off-by: Your Real Name <your@email.address>+ at the end of the
+commit message. +git commit -s+ does that for you, if configured
+properly. The +Signed-off-by+ tag means that you publish the patch
+under the Buildroot license (i.e. GPLv2, except for package patches,
+which have the upstream license), and that you are allowed to do so.
+See http://developercertificate.org/[the Developer Certificate of
+Origin] for details.
+
+When adding new packages, you should submit every package in a
+separate patch. This patch should have the update to
++package/Config.in+, the package +Config.in+ file, the +.mk+ file, the
++.hash+ file, any init script, and all package patches. If the package
+has many sub-options, these are sometimes better added as separate
+follow-up patches. The summary line should be something like
++<packagename>: new package+. The body of the commit message can be
+empty for simple packages, or it can contain the description of the
+package (like the Config.in help text). If anything special has to be
+done to build the package, this should also be explained explicitly in
+the commit message body.
+
+When you bump a package to a new version, you should also submit a
+separate patch for each package. Don't forget to update the +.hash+
+file, or add it if it doesn't exist yet. Also don't forget to check if
+the +_LICENSE+ and +_LICENSE_FILES+ are still valid. The summary line
+should be something like +<packagename>: bump to version <new
+version>+. If the new version only contains security updates compared
+to the existing one, the summary should be +<packagename>: security
+bump to version <new version>+ and the commit message body should show
+the CVE numbers that are fixed. If some package patches can be removed
+in the new version, it should be explained explicitly why they can be
+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.
+
+==== Preparing a patch series
+
+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
diff --git a/docs/manual/legal-notice.txt b/docs/manual/legal-notice.txt
index 58952243e9..0572daee34 100644
--- a/docs/manual/legal-notice.txt
+++ b/docs/manual/legal-notice.txt
@@ -74,6 +74,9 @@ file to inform you of relevant material that could not be saved.
 Here is a list of the licenses that are most widely used by packages in
 Buildroot, with the name used in the manifest files:
 
+* `AGPLv3`:
+  http://www.gnu.org/licenses/agpl-3.0.en.html[
+  GNU Affero General Public License, version 3];
 * `GPLv2`:
   http://www.gnu.org/licenses/old-licenses/gpl-2.0.html[
   GNU General Public License, version 2];
@@ -131,11 +134,13 @@ Buildroot, with the name used in the manifest files:
   http://apache.org/licenses/LICENSE-2.0.html[
   Apache License, version 2.0];
 
+[[legal-info-buildroot]]
 === Complying with the Buildroot license
 
 Buildroot itself is an open source software, released under the
-http://www.gnu.org/licenses/old-licenses/gpl-2.0.html[GNU General Public
-License, version 2] or (at your option) any later version.
+http://www.gnu.org/licenses/old-licenses/gpl-2.0.html[GNU General
+Public License, version 2] or (at your option) any later version, with
+the exception of the package patches detailed below.
 However, being a build system, it is not normally part of the end product:
 if you develop the root filesystem, kernel, bootloader or toolchain for a
 device, the code of Buildroot is only present on the development machine, not
@@ -156,3 +161,14 @@ material that must be redistributed.
 
 Keep in mind that this is only the Buildroot developers' opinion, and you
 should consult your legal department or lawyer in case of any doubt.
+
+==== Patches to packages
+
+Buildroot also bundles patch files, which are applied to the sources
+of the various packages. Those patches are not covered by the license
+of Buildroot. Instead, they are covered by the license of the software
+to which the patches are applied. When said software is available
+under multiple licenses, the Buildroot patches are only provided under
+the publicly accessible licenses.
+
+See xref:patch-policy[] for the technical details.
diff --git a/docs/manual/patch-policy.txt b/docs/manual/patch-policy.txt
index 0b4604e5c3..5a1fe4f46e 100644
--- a/docs/manual/patch-policy.txt
+++ b/docs/manual/patch-policy.txt
@@ -90,8 +90,8 @@ If something goes wrong in the steps _3_ or _4_, then the build fails.
 
 === Format and licensing of the package patches
 
-Patches are released under the same license as the software that is
-modified.
+Patches are released under the same license as the software they apply
+to (see xref:legal-info-buildroot[]).
 
 A message explaining what the patch does, and why it is needed, should
 be added in the header commentary of the patch.