Chapter 10. Contributing to Buildroot

If you want to contribute to Buildroot, you will need a git view of the project. Refer to Section 2.2, “Getting Buildroot” to get it.

Currently, the mailing list is the central place for contribution. If you have not already subscribed to it, then refer to Section 9.1.1, “Subscribing to the mailing list”.

Recently, a web interface is also used to manage patches sent to the mailing list, see Section 9.3, “Patchwork”.

Note

Please, do not attach patches to bugs, send them to the mailing list instead (see Section 10.1, “Submitting patches”).

10.1. Submitting patches

When your changes are done, and committed in your local git view, 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

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

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@busybox.net outgoing/*

Note that git should be configured to use your mail account. To configure git, see man git-send-email or google it.

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.

10.1.1. 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 [4];
  • whenever you feel it will help presenting your work, your choices, the review process, etc.

10.1.2. 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, the changelog may be added in the cover letter rather than in the individual commits.

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 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 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

10.2. Reviewing/Testing 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.

Some tags are used to help following the state of any patch posted on the mailing-list:

Acked-by
Indicates that the patch can be committed.
Tested-by
Indicates that the patch has been tested. It is useful but not necessary to add a comment about what has been tested.

10.3. Autobuild

The Buildroot community is currently setting up automatic builds in order to test more and more configurations. All build results are available at http://autobuild.buildroot.org

A good way to contribute is by fixing broken builds.

In the commit message of a patch fixing an autobuild, add a reference to the build result directory (the dir link in the data column):

Fixes http://autobuild.buildroot.org/results/51000a9d4656afe9e0ea6f07b9f8ed374c2e4069

10.4. Reporting issues/bugs, get help

Before reporting any issue, please check the mailing list archive Section 9.1.1, “Subscribing to the mailing list” in case someone has already reported and fixed a similar problem.

However you choose to report bugs or get help, opening a bug Section 9.4, “Bugtracker” or send a mail to the mailing list Section 9.1.1, “Subscribing 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) which the build fails
  • the command that fails and its output
  • any information you think that may be relevant

Additionnally, your can add the .config file.

If some of these details are too large, do not hesitate to use a pastebin service (see http://www.similarsitesearch.com/alternatives-to/pastebin.com).



[4] RFC: (Request for comments) change proposal