diff options
| -rw-r--r-- | docs/manual/contribute.txt | 74 |
1 files changed, 74 insertions, 0 deletions
diff --git a/docs/manual/contribute.txt b/docs/manual/contribute.txt index 90c73de5f..1b1f4de19 100644 --- a/docs/manual/contribute.txt +++ b/docs/manual/contribute.txt @@ -184,6 +184,80 @@ instead_. If you made some changes to Buildroot and you would like to contribute 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_ |