// -*- 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:mailing-list-subscribe[].

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.

[[submitting-patches]]
Submitting patches
------------------

[NOTE]
_Please, do not attach patches to bugs, send them to the mailing list
instead_.

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

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.

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

Reviewing/Testing patches
-------------------------

The review process for new patches is done over the mailing list. Once
a patch is submitted to the mailing list, other developers will provide
feedback to the patch via emails sent through the mailing list.

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.

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

Tested-by:: Indicates that the patch has been tested in one way or
  another. 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.

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

[[reporting-bugs]]
Reporting issues/bugs, get help
-------------------------------

Before reporting any issue, please check
xref:mailing-list-subscribe[the mailing list archive] in case someone has
already reported and fixed a similar problem.

However you choose to report bugs or get help,
xref:bugtracker[opening a bug] or
xref:mailing-list-subscribe[send 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) 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[]).
