X-Git-Url: https://review.fuel-infra.org/gitweb?a=blobdiff_plain;f=cirros-testvm%2Fsrc-cirros%2Fbuildroot-2015.05%2Fbuild%2Fdocs%2Fmanual%2Fcontribute.txt;fp=cirros-testvm%2Fsrc-cirros%2Fbuildroot-2015.05%2Fbuild%2Fdocs%2Fmanual%2Fcontribute.txt;h=5f0762f4a3dec8d94f96fb54daa1253871dbccc1;hb=b0a0f15dfaa205161a7fcb20cf1b8cd4948c2ef3;hp=0000000000000000000000000000000000000000;hpb=c6ac3cd55ee2da956195eee393b0882105dfad4e;p=packages%2Ftrusty%2Fcirros-testvm.git diff --git a/cirros-testvm/src-cirros/buildroot-2015.05/build/docs/manual/contribute.txt b/cirros-testvm/src-cirros/buildroot-2015.05/build/docs/manual/contribute.txt new file mode 100644 index 0000000..5f0762f --- /dev/null +++ b/cirros-testvm/src-cirros/buildroot-2015.05/build/docs/manual/contribute.txt @@ -0,0 +1,334 @@ +// -*- 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/