// -*- mode:doc; -*- // vim: set syntax=asciidoc: == Contributing to Buildroot 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. 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:community-resources[] for the subscription link. 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. === 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. === Analyzing and fixing autobuild failures The Buildroot autobuilders are a set of build machines that continuously run Buildroot builds based on random configurations. This is done for all architectures supported by Buildroot, with various toolchains, and with a random selection of packages. With the large commit activity on Buildroot, these autobuilders are a great help in detecting problems very early after commit. All build results are available at http://autobuild.buildroot.org[], statistics are at http://autobuild.buildroot.org/stats.php[]. Every day, an overview of all failed packages is sent to the mailing list. Detecting problems is great, but obviously these problems have to be fixed as well. Your contribution is very welcome here! There are basically two things that can be done: - Analyzing the problems. The daily summary mails do not contain details about the actual failures: in order to see what's going on you have to open the build log and check the last output. Having someone doing this for all packages in the mail is very useful for other developers, as they can make a quick initial analysis based on this output alone. - Fixing a problem. When fixing autobuild failures, you should follow these steps: . Check if you can reproduce the problem by building with the same configuration. You can do this manually, or use the http://git.buildroot.org/buildroot-test/tree/utils/br-reproduce-build[br-reproduce-build] script that will automatically clone a Buildroot git repository, checkout the correct revision, download and set the right configuration, and start the build. . Analyze the problem and create a fix. . Verify that the problem is really fixed by starting from a clean Buildroot tree and only applying your fix. . Send the fix to the Buildroot mailing list (see xref:submitting-patches[]). In case you created a patch against the package sources, you should also send the patch upstream so that the problem will be fixed in a later release, and the patch in Buildroot can be removed. In the commit message of a patch fixing an autobuild failure, add a reference to the build result directory, as follows: --------------------- 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 to judge which patches are ready to apply and which ones aren't. Contributors can greatly help here by reviewing and testing these patches. 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. To indicate approval of a patch, there are three formal tags that keep track of this approval. To add your tag to a patch, reply to it with the approval tag below the original author's Signed-off-by line. These tags will be picked up automatically by patchwork (see xref:apply-patches-patchwork[]) and will be part of the commit log when the patch is accepted. Tested-by:: Indicates that the patch has been tested successfully. 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. [[apply-patches-patchwork]] ==== Applying Patches from Patchwork The main use of Buildroot's Patchwork website for a developer is for pulling in patches into their local git repository for testing purposes. When browsing patches in the patchwork management interface, an +mbox+ link is provided at the top of the page. Copy this link address and run the following commands: --------------------- $ git checkout -b $ wget -O - | git am --------------------- Another option for applying patches is to create a bundle. A bundle is a set of patches that you can group together using the patchwork interface. Once the bundle is created and the bundle is made public, you can copy the +mbox+ link for the bundle and apply the bundle using the above commands. === Work on items from the TODO list If you want to contribute to Buildroot but don't know where to start, 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 [NOTE] _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: --------------------- $ git fetch --all --tags $ git rebase origin/master --------------------- Now, you are ready to generate then submit your patch set. To generate it, run: --------------------- $ git format-patch -M -n -s -o outgoing origin/master --------------------- This will generate patch files in the +outgoing+ subdirectory, 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. Lastly, send/submit your patch set to the Buildroot mailing list: --------------------- $ git send-email --to buildroot@buildroot.org outgoing/* --------------------- Note that +git+ should be configured to use your mail account. To configure +git+, see +man git-send-email+ or google it. 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 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). This will generate a template for an introduction e-mail to your patch series. 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 each commit should include a changelog of the modifications between each submission. Note that when your patch series is introduced by a cover letter, an overall changelog may be added to the cover letter in addition to the changelog in the individual commits. The best thing to rework a patch series is by interactive rebasing: +git rebase -i origin/master+. Consult the git manual for more information. When added to the individual commits, 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. This is the intended behavior: the changelog is not meant to be preserved forever in the +git+ history of the project. Hereafter the recommended layout: --------------- Patch title: short explanation, max 72 chars A paragraph that explains the problem, and how it manifests itself. If the problem is complex, it is OK to add more paragraphs. All paragraphs should be wrapped at 72 characters. A paragraph that explains the root cause of the problem. Again, more than on paragraph is OK. Finally, one or more paragraphs that explain how the problem is solved. Don't hesitate to explain complex solutions in detail. Signed-off-by: John DOE --- 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 -s -o outgoing origin/master --------------------- [[reporting-bugs]] === Reporting issues/bugs or getting help Before reporting any issue, please check in xref:community-resources[the mailing list archive] whether someone has already reported and/or fixed a similar problem. However you choose to report bugs or get help, either by opening a bug in the xref:community-resources[bug tracker] or by xref:community-resources[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. Try to think as if you were trying to help someone else; in that case, what would you need? Here is a short list of details to provide in such case: * host machine (OS/release) * version of Buildroot * target for 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 Additionally, you should add the +.config+ file (or if you know how, a +defconfig+; see xref:customize-store-buildroot-config[]). If some of these details are too large, do not hesitate to use a pastebin service. Note that not all available pastebin services will preserve Unix-style line terminators when downloading raw pastes. Following pastebin services are known to work correctly: - https://gist.github.com/ - http://code.bulix.org/