2012-11-11 04:14:53 +01:00
|
|
|
// -*- mode:doc; -*-
|
2013-02-13 13:59:02 +01:00
|
|
|
// vim: set syntax=asciidoc:
|
2012-11-11 04:14:53 +01:00
|
|
|
|
2013-03-25 05:48:10 +01:00
|
|
|
Contributing to Buildroot
|
2014-03-05 17:24:27 +01:00
|
|
|
=========================
|
|
|
|
|
|
|
|
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
|
2012-11-11 04:14:53 +01:00
|
|
|
xref:mailing-list-subscribe[].
|
|
|
|
|
2014-03-05 17:24:27 +01:00
|
|
|
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.
|
2012-11-11 04:14:53 +01:00
|
|
|
|
2014-03-05 17:24:28 +01:00
|
|
|
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.
|
|
|
|
|
2014-03-06 11:07:29 +01:00
|
|
|
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
|
|
|
|
---------------------
|
|
|
|
|
2012-11-11 04:14:53 +01:00
|
|
|
[[submitting-patches]]
|
|
|
|
Submitting patches
|
|
|
|
------------------
|
|
|
|
|
2014-03-05 17:24:27 +01:00
|
|
|
[NOTE]
|
|
|
|
_Please, do not attach patches to bugs, send them to the mailing list
|
|
|
|
instead_.
|
|
|
|
|
2012-11-11 04:14:53 +01:00
|
|
|
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:
|
|
|
|
|
|
|
|
---------------------
|
2013-08-09 12:16:48 +02:00
|
|
|
$ git fetch --all --tags
|
|
|
|
$ git rebase origin/master
|
2012-11-11 04:14:53 +01:00
|
|
|
---------------------
|
|
|
|
|
|
|
|
Here, you are ready to generate then submit your patch set.
|
|
|
|
|
|
|
|
To generate it, run:
|
|
|
|
|
|
|
|
---------------------
|
2013-08-09 12:16:48 +02:00
|
|
|
$ git format-patch -M -n -s -o outgoing origin/master
|
2012-11-11 04:14:53 +01:00
|
|
|
---------------------
|
|
|
|
|
|
|
|
This will generate patch files in the +outgoing+ subdirectory,
|
2013-09-16 15:07:28 +02:00
|
|
|
automatically adding the +Signed-off-by+ line.
|
2012-11-11 04:14:53 +01:00
|
|
|
|
|
|
|
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:
|
|
|
|
|
|
|
|
---------------------
|
2014-02-12 17:54:57 +01:00
|
|
|
$ git send-email --to buildroot@buildroot.org outgoing/*
|
2012-11-11 04:14:53 +01:00
|
|
|
---------------------
|
|
|
|
|
|
|
|
Note that +git+ should be configured to use your mail account.
|
|
|
|
To configure +git+, see +man git-send-email+ or google it.
|
|
|
|
|
2012-11-16 05:54:19 +01:00
|
|
|
Make sure posted *patches are not line-wrapped*, otherwise they cannot
|
2012-11-11 04:14:53 +01:00
|
|
|
easily be applied. In such a case, fix your e-mail client, or better,
|
|
|
|
use +git send-email+ to send your patches.
|
|
|
|
|
2013-08-09 12:16:46 +02:00
|
|
|
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.
|
|
|
|
|
2013-09-16 15:07:28 +02:00
|
|
|
Signed-off-by: John Doe <john.doe@noname.org>
|
2013-08-09 12:16:46 +02:00
|
|
|
---
|
|
|
|
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
|
|
|
|
---------------------
|
|
|
|
|
2012-11-11 04:14:53 +01:00
|
|
|
Reviewing/Testing patches
|
|
|
|
-------------------------
|
|
|
|
|
2013-10-09 22:46:15 +02:00
|
|
|
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.
|
|
|
|
|
2012-11-11 04:14:53 +01:00
|
|
|
In the review process, do not hesitate to respond to patch submissions
|
|
|
|
for remarks, suggestions or anything that will help everyone to
|
2013-10-09 22:46:15 +02:00
|
|
|
understand the patches and make them better. Please use internet
|
|
|
|
style replies in plain text emails when responding to patch
|
|
|
|
submissions.
|
2012-11-11 04:14:53 +01:00
|
|
|
|
|
|
|
Some tags are used to help following the state of any patch posted on
|
|
|
|
the mailing-list:
|
|
|
|
|
2014-03-02 15:17:22 +01:00
|
|
|
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.
|
2012-11-11 04:14:53 +01:00
|
|
|
|
2013-10-09 22:46:15 +02:00
|
|
|
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.
|
|
|
|
|
2012-11-11 04:14:53 +01:00
|
|
|
[[reporting-bugs]]
|
|
|
|
Reporting issues/bugs, get help
|
|
|
|
-------------------------------
|
|
|
|
|
2012-11-16 05:54:19 +01:00
|
|
|
Before reporting any issue, please check
|
|
|
|
xref:mailing-list-subscribe[the mailing list archive] in case someone has
|
2012-11-11 04:14:53 +01:00
|
|
|
already reported and fixed a similar problem.
|
|
|
|
|
2012-11-16 05:54:19 +01:00
|
|
|
However you choose to report bugs or get help,
|
2012-11-11 04:14:53 +01:00
|
|
|
xref:bugtracker[opening a bug] or
|
2012-11-16 05:54:19 +01:00
|
|
|
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
|
2012-11-11 04:14:53 +01:00
|
|
|
find a solution to the issue.
|
|
|
|
|
2012-11-16 05:54:19 +01:00
|
|
|
Try to think as if you were trying to help someone else; in
|
2012-11-11 04:14:53 +01:00
|
|
|
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.
|
|
|
|
|
2012-11-16 05:54:19 +01:00
|
|
|
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[]).
|