--- /dev/null
+// -*- 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 <test-branch-name>
+$ wget -O - <mbox-url> | 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 <john.doe@example.net>
+
+---
+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/
Code Review / packages / trusty / cirros-testvm.git / blobdiff