cirros-testvm/src-cirros/buildroot-2015.05/build/docs/manual/contribute.txt

   1 // -*- mode:doc; -*-
   2 // vim: set syntax=asciidoc:
   3
   4 == Contributing to Buildroot
   5
   6 There are many ways in which you can contribute to Buildroot: analyzing
   7 and fixing bugs, analyzing and fixing package build failures detected by
   8 the autobuilders, testing and reviewing patches sent by other
   9 developers, working on the items in our TODO list and sending your own
  10 improvements to Buildroot or its manual. The following sections give a
  11 little more detail on each of these items.
  12
  13 If you are interested in contributing to Buildroot, the first thing you
  14 should do is to subscribe to the Buildroot mailing list. This list is
  15 the main way of interacting with other Buildroot developers and to send
  16 contributions to. If you aren't subscribed yet, then refer to
  17 xref:community-resources[] for the subscription link.
  18
  19 If you are going to touch the code, it is highly recommended to use a
  20 git repository of Buildroot, rather than starting from an extracted
  21 source code tarball. Git is the easiest way to develop from and directly
  22 send your patches to the mailing list. Refer to xref:getting-buildroot[]
  23 for more information on obtaining a Buildroot git tree.
  24
  25 === Reproducing, analyzing and fixing bugs
  26
  27 A first way of contributing is to have a look at the open bug reports in
  28 the https://bugs.busybox.net/buglist.cgi?product=buildroot[Buildroot bug
  29 tracker]. As we strive to keep the bug count as small as possible, all
  30 help in reproducing, analyzing and fixing reported bugs is more than
  31 welcome. Don't hesitate to add a comment to bug reports reporting your
  32 findings, even if you don't yet see the full picture.
  33
  34 === Analyzing and fixing autobuild failures
  35
  36 The Buildroot autobuilders are a set of build machines that continuously
  37 run Buildroot builds based on random configurations. This is done for
  38 all architectures supported by Buildroot, with various toolchains, and
  39 with a random selection of packages. With the large commit activity on
  40 Buildroot, these autobuilders are a great help in detecting problems
  41 very early after commit.
  42
  43 All build results are available at http://autobuild.buildroot.org[],
  44 statistics are at http://autobuild.buildroot.org/stats.php[]. Every day,
  45 an overview of all failed packages is sent to the mailing list.
  46
  47 Detecting problems is great, but obviously these problems have to be
  48 fixed as well. Your contribution is very welcome here! There are
  49 basically two things that can be done:
  50
  51 - Analyzing the problems. The daily summary mails do not contain details
  52   about the actual failures: in order to see what's going on you have to
  53   open the build log and check the last output. Having someone doing
  54   this for all packages in the mail is very useful for other developers,
  55   as they can make a quick initial analysis based on this output alone.
  56
  57 - Fixing a problem. When fixing autobuild failures, you should follow
  58   these steps:
  59   . Check if you can reproduce the problem by building with the same
  60     configuration. You can do this manually, or use the
  61     http://git.buildroot.org/buildroot-test/tree/utils/br-reproduce-build[br-reproduce-build]
  62     script that will automatically clone a Buildroot git repository,
  63     checkout the correct revision, download and set the right
  64     configuration, and start the build.
  65   . Analyze the problem and create a fix.
  66   . Verify that the problem is really fixed by starting from a clean
  67     Buildroot tree and only applying your fix.
  68   . Send the fix to the Buildroot mailing list (see
  69     xref:submitting-patches[]). In case you created a patch against the
  70     package sources, you should also send the patch upstream so that the
  71     problem will be fixed in a later release, and the patch in Buildroot
  72     can be removed.
  73     In the commit message of a patch fixing an autobuild failure, add a
  74     reference to the build result directory, as follows:
  75 ---------------------
  76 Fixes http://autobuild.buildroot.org/results/51000a9d4656afe9e0ea6f07b9f8ed374c2e4069
  77 ---------------------
  78
  79 === Reviewing and testing patches
  80
  81 With the amount of patches sent to the mailing list each day, the
  82 maintainer has a very hard job to judge which patches are ready to apply
  83 and which ones aren't. Contributors can greatly help here by reviewing
  84 and testing these patches.
  85
  86 In the review process, do not hesitate to respond to patch submissions
  87 for remarks, suggestions or anything that will help everyone to
  88 understand the patches and make them better. Please use internet
  89 style replies in plain text emails when responding to patch
  90 submissions.
  91
  92 To indicate approval of a patch, there are three formal tags that keep
  93 track of this approval. To add your tag to a patch, reply to it with the
  94 approval tag below the original author's Signed-off-by line. These tags
  95 will be picked up automatically by patchwork (see
  96 xref:apply-patches-patchwork[]) and will be part of the commit log when
  97 the patch is accepted.
  98
  99 Tested-by:: Indicates that the patch has been tested successfully.
 100   You are encouraged to specify what kind of testing you performed
 101   (compile-test on architecture X and Y, runtime test on target A,
 102   ...). This additional information helps other testers and the
 103   maintainer.
 104
 105 Reviewed-by:: Indicates that you code-reviewed the patch and did your
 106   best in spotting problems, but you are not sufficiently familiar with
 107   the area touched to provide an Acked-by tag. This means that there
 108   may be remaining problems in the patch that would be spotted by
 109   someone with more experience in that area. Should such problems be
 110   detected, your Reviewed-by tag remains appropriate and you cannot
 111   be blamed.
 112
 113 Acked-by:: Indicates that you code-reviewed the patch and you are
 114   familiar enough with the area touched to feel that the patch can be
 115   committed as-is (no additional changes required). In case it later
 116   turns out that something is wrong with the patch, your Acked-by could
 117   be considered inappropriate. The difference between Acked-by and
 118   Reviewed-by is thus mainly that you are prepared to take the blame on
 119   Acked patches, but not on Reviewed ones.
 120
 121 If you reviewed a patch and have comments on it, you should simply reply
 122 to the patch stating these comments, without providing a Reviewed-by or
 123 Acked-by tag. These tags should only be provided if you judge the patch
 124 to be good as it is.
 125
 126 It is important to note that neither Reviewed-by nor Acked-by imply
 127 that testing has been performed. To indicate that you both reviewed and
 128 tested the patch, provide two separate tags (Reviewed/Acked-by and
 129 Tested-by).
 130
 131 Note also that _any developer_ can provide Tested/Reviewed/Acked-by
 132 tags, without exception, and we encourage everyone to do this. Buildroot
 133 does not have a defined group of _core_ developers, it just so happens
 134 that some developers are more active than others. The maintainer will
 135 value tags according to the track record of their submitter. Tags
 136 provided by a regular contributor will naturally be trusted more than
 137 tags provided by a newcomer. As you provide tags more regularly, your
 138 'trustworthiness' (in the eyes of the maintainer) will go up, but _any_
 139 tag provided is valuable.
 140
 141 Buildroot's Patchwork website can be used to pull in patches for testing
 142 purposes. Please see xref:apply-patches-patchwork[] for more
 143 information on using Buildroot's Patchwork website to apply patches.
 144
 145 [[apply-patches-patchwork]]
 146 ==== Applying Patches from Patchwork
 147
 148 The main use of Buildroot's Patchwork website for a developer is for
 149 pulling in patches into their local git repository for testing
 150 purposes.
 151
 152 When browsing patches in the patchwork management interface, an +mbox+
 153 link is provided at the top of the page. Copy this link address and
 154 run the following commands:
 155
 156 ---------------------
 157 $ git checkout -b <test-branch-name>
 158 $ wget -O - <mbox-url> | git am
 159 ---------------------
 160
 161 Another option for applying patches is to create a bundle. A bundle is
 162 a set of patches that you can group together using the patchwork
 163 interface. Once the bundle is created and the bundle is made public,
 164 you can copy the +mbox+ link for the bundle and apply the bundle
 165 using the above commands.
 166
 167
 168 === Work on items from the TODO list
 169
 170 If you want to contribute to Buildroot but don't know where to start,
 171 and you don't like any of the above topics, you can always work on items
 172 from the http://elinux.org/Buildroot#Todo_list[Buildroot TODO list].
 173 Don't hesitate to discuss an item first on the mailing list or on IRC.
 174 Do edit the wiki to indicate when you start working on an item, so we
 175 avoid duplicate efforts.
 176
 177 [[submitting-patches]]
 178 === Submitting patches
 179
 180 [NOTE]
 181 _Please, do not attach patches to bugs, send them to the mailing list
 182 instead_.
 183
 184 If you made some changes to Buildroot and you would like to contribute
 185 them to the Buildroot project, proceed as follows. Starting from the
 186 changes committed in your local git view, _rebase_ your development
 187 branch on top of the upstream tree before generating a patch set. To do
 188 so, run:
 189
 190 ---------------------
 191 $ git fetch --all --tags
 192 $ git rebase origin/master
 193 ---------------------
 194
 195 Now, you are ready to generate then submit your patch set.
 196
 197 To generate it, run:
 198
 199 ---------------------
 200 $ git format-patch -M -n -s -o outgoing origin/master
 201 ---------------------
 202
 203 This will generate patch files in the +outgoing+ subdirectory,
 204 automatically adding the +Signed-off-by+ line.
 205
 206 Once patch files are generated, you can review/edit the commit message
 207 before submitting them, using your favorite text editor.
 208
 209 Lastly, send/submit your patch set to the Buildroot mailing list:
 210
 211 ---------------------
 212 $ git send-email --to buildroot@buildroot.org outgoing/*
 213 ---------------------
 214
 215 Note that +git+ should be configured to use your mail account.
 216 To configure +git+, see +man git-send-email+ or google it.
 217
 218 If you do not use +git send-email+, make sure posted *patches are not
 219 line-wrapped*, otherwise they cannot easily be applied. In such a case,
 220 fix your e-mail client, or better yet, learn to use +git send-email+.
 221
 222 ==== Cover letter
 223
 224 If you want to present the whole patch set in a separate mail, add
 225 +--cover-letter+ to the +git format-patch+ command (see +man
 226 git-format-patch+ for further information). This will generate a
 227 template for an introduction e-mail to your patch series.
 228
 229 A 'cover letter' may be useful to introduce the changes you propose
 230 in the following cases:
 231
 232 * large number of commits in the series;
 233
 234 * deep impact of the changes in the rest of the project;
 235
 236 * RFC footnote:[RFC: (Request for comments) change proposal];
 237
 238 * whenever you feel it will help presenting your work, your choices,
 239   the review process, etc.
 240
 241 ==== Patch revision changelog
 242
 243 When improvements are requested, the new revision of each commit
 244 should include a changelog of the modifications between each
 245 submission. Note that when your patch series is introduced by a cover
 246 letter, an overall changelog may be added to the cover letter in
 247 addition to the changelog in the individual commits.
 248 The best thing to rework a patch series is by interactive rebasing:
 249 +git rebase -i origin/master+. Consult the git manual for more
 250 information.
 251
 252 When added to the individual commits, this changelog is added when
 253 editing the commit message. Below the +Signed-off-by+ section, add
 254 +---+ and your changelog.
 255
 256 Although the changelog will be visible for the reviewers in the mail
 257 thread, as well as in http://patchwork.buildroot.org[patchwork], +git+
 258 will automatically ignores lines below +---+ when the patch will be
 259 merged. This is the intended behavior: the changelog is not meant to
 260 be preserved forever in the +git+ history of the project.
 261
 262 Hereafter the recommended layout:
 263
 264 ---------------
 265 Patch title: short explanation, max 72 chars
 266
 267 A paragraph that explains the problem, and how it manifests itself. If
 268 the problem is complex, it is OK to add more paragraphs. All paragraphs
 269 should be wrapped at 72 characters.
 270
 271 A paragraph that explains the root cause of the problem. Again, more
 272 than on paragraph is OK.
 273
 274 Finally, one or more paragraphs that explain how the problem is solved.
 275 Don't hesitate to explain complex solutions in detail.
 276
 277 Signed-off-by: John DOE <john.doe@example.net>
 278
 279 ---
 280 Changes v2 -> v3:
 281   - foo bar  (suggested by Jane)
 282   - bar buz
 283
 284 Changes v1 -> v2:
 285   - alpha bravo  (suggested by John)
 286   - charly delta
 287 ---------------
 288
 289 Any patch revision should include the version number. The version number
 290 is simply composed of the letter +v+ followed by an +integer+ greater or
 291 equal to two (i.e. "PATCH v2", "PATCH v3" ...).
 292
 293 This can be easily handled with +git format-patch+ by using the option
 294 +--subject-prefix+:
 295
 296 ---------------------
 297 $ git format-patch --subject-prefix "PATCH v4" \
 298     -M -s -o outgoing origin/master
 299 ---------------------
 300
 301 [[reporting-bugs]]
 302 === Reporting issues/bugs or getting help
 303
 304 Before reporting any issue, please check in
 305 xref:community-resources[the mailing list archive] whether someone has
 306 already reported and/or fixed a similar problem.
 307
 308 However you choose to report bugs or get help, either by
 309 opening a bug in the xref:community-resources[bug tracker] or by
 310 xref:community-resources[sending a mail to the mailing list], there are
 311 a number of details to provide in order to help people reproduce and
 312 find a solution to the issue.
 313
 314 Try to think as if you were trying to help someone else; in
 315 that case, what would you need?
 316
 317 Here is a short list of details to provide in such case:
 318
 319 * host machine (OS/release)
 320 * version of Buildroot
 321 * target for which the build fails
 322 * package(s) for which the build fails
 323 * the command that fails and its output
 324 * any information you think that may be relevant
 325
 326 Additionally, you should add the +.config+ file (or if you know how, a
 327 +defconfig+; see xref:customize-store-buildroot-config[]).
 328
 329 If some of these details are too large, do not hesitate to use a
 330 pastebin service. Note that not all available pastebin services will
 331 preserve Unix-style line terminators when downloading raw pastes.
 332 Following pastebin services are known to work correctly:
 333 - https://gist.github.com/
 334 - http://code.bulix.org/