docs/manual/contribute.txt

1 // -*- mode:doc; -*-
4 == Contributing to Buildroot
6 There are many ways in which you can contribute to Buildroot: analyzing
10 improvements to Buildroot or its manual. The following sections give a
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
17 xref:community-resources[] for the subscription link.
20 git repository of Buildroot, rather than starting from an extracted
22 send your patches to the mailing list. Refer to xref:getting-buildroot[]
23 for more information on obtaining a Buildroot git tree.
28 the https://bugs.buildroot.org/buglist.cgi?product=buildroot[Buildroot bug
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
40 Buildroot, these autobuilders are a great help in detecting problems
43 All build results are available at http://autobuild.buildroot.org[],
44 statistics are at http://autobuild.buildroot.org/stats.php[]. Every day,
51 - Analyzing the problems. The daily summary mails do not contain details
57 - Fixing a problem. When fixing autobuild failures, you should follow
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,
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
71     problem will be fixed in a later release, and the patch in Buildroot
75 ---------------------
76 Fixes: http://autobuild.buildroot.org/results/51000a9d4656afe9e0ea6f07b9f8ed374c2e4069
77 ---------------------
94 approval tag below the original author's Signed-off-by line. These tags
96 xref:apply-patches-patchwork[]) and will be part of the commit log when
99 Tested-by:: Indicates that the patch has been tested successfully.
101   (compile-test on architecture X and Y, runtime test on target A,
105 Reviewed-by:: Indicates that you code-reviewed the patch and did your
107   the area touched to provide an Acked-by tag. This means that there
110   detected, your Reviewed-by tag remains appropriate and you cannot
113 Acked-by:: Indicates that you code-reviewed the patch and you are
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
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
126 It is important to note that neither Reviewed-by nor Acked-by imply
128 tested the patch, provide two separate tags (Reviewed/Acked-by and
129 Tested-by).
131 Note also that _any developer_ can provide Tested/Reviewed/Acked-by
132 tags, without exception, and we encourage everyone to do this. Buildroot
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.
145 [[apply-patches-patchwork]]
148 The main use of Buildroot's Patchwork website for a developer is for
156 ---------------------
157 $ git checkout -b <test-branch-name>
158 $ wget -O - <mbox-url> | git am
159 ---------------------
170 If you want to contribute to Buildroot but don't know where to start,
172 from the http://elinux.org/Buildroot#Todo_list[Buildroot TODO list].
177 [[submitting-patches]]
184 If you made some changes to Buildroot and you would like to contribute
185 them to the Buildroot project, proceed as follows.
204 * +package/pkg-generic: postpone evaluation of dependency conditions+
206 * +boot/uboot: needs host-{flex,bison}+
208 * +support/testing: add python-ubjson tests+
236 https://git-scm.com/book/en/v2/Git-Tools-Rewriting-History[in the Pro
238 +git reset --soft origin/master+ and select individual changes with
239 +git add -i+ or +git add -p+.
242 +Signed-off-by: Your Real Name <your@email.address>+ at the end of the
243 commit message. +git commit -s+ does that for you, if configured
244 properly. The +Signed-off-by+ tag means that you publish the patch
245 under the Buildroot license (i.e. GPL-2.0+, except for package patches,
254 has many sub-options, these are sometimes better added as separate
255 follow-up patches. The summary line should be something like
282 Buildroot provides a handy tool to check for common coding style
283 mistakes on files you created or modified, called +check-package+ (see
284 xref:check-package[] for more information).
292 ---------------------
293 $ git fetch --all --tags
295 ---------------------
301 ---------------------
302 $ git format-patch -M -n -s -o outgoing origin/master
303 ---------------------
306 automatically adding the +Signed-off-by+ line.
311 Buildroot provides a handy tool to know to whom your patches should be
312 sent, called +get-developers+ (see xref:DEVELOPERS[] for more
314 +git send-email+ command to use:
316 ---------------------
317 $ ./utils/get-developers outgoing/*
318 ---------------------
320 Use the output of +get-developers+ to send your patches:
322 ---------------------
323 $ git send-email --to buildroot@buildroot.org --cc bob --cc alice outgoing/*
324 ---------------------
326 Alternatively, +get-developers -e+ can be used directly with the
327 +--cc-cmd+ argument to +git send-email+ to automatically CC the
330 ---------------------
331 $ git send-email --to buildroot@buildroot.org \
332       --cc-cmd './utils/get-developers -e' origin/master
333 ---------------------
337 ---------------------
338 $ git config sendemail.to buildroot@buildroot.org
339 $ git config sendemail.ccCmd "$(pwd)/utils/get-developers -e"
340 ---------------------
344 ---------------------
345 $ git send-email origin/master
346 ---------------------
349 To configure +git+, see +man git-send-email+ or google it.
351 If you do not use +git send-email+, make sure posted *patches are not
352 line-wrapped*, otherwise they cannot easily be applied. In such a case,
353 fix your e-mail client, or better yet, learn to use +git send-email+.
358 +--cover-letter+ to the +git format-patch+ command (see +man
359 git-format-patch+ for further information). This will generate a
360 template for an introduction e-mail to your patch series.
378 post-commit note specifying what branches are affected:
380 ----
383 Signed-off-by: Your Real Name <your@email.address>
384 ---
387 ----
396 This can be done with the +git format-patch+ flag +--subject-prefix+:
398 ---------------------
399 $ git format-patch --subject-prefix "PATCH 2020.02.x" \
400     -M -s -o outgoing origin/2020.02.x
401 ---------------------
403 Then send the patches with +git send-email+, as described above.
413 +git rebase -i origin/master+. Consult the git manual for more
417 editing the commit message. Below the +Signed-off-by+ section, add
418 +---+ and your changelog.
421 thread, as well as in http://patchwork.buildroot.org[patchwork], +git+
422 will automatically ignores lines below +---+ when the patch will be
428 ---------------
441 Signed-off-by: John DOE <john.doe@example.net>
443 ---
444 Changes v2 -> v3:
445   - foo bar  (suggested by Jane)
446   - bar buz
448 Changes v1 -> v2:
449   - alpha bravo  (suggested by John)
450   - charly delta
451 ---------------
457 This can be easily handled with +git format-patch+ by using the option
458 +--subject-prefix+:
460 ---------------------
461 $ git format-patch --subject-prefix "PATCH v4" \
462     -M -s -o outgoing origin/master
463 ---------------------
465 Since git version 1.8.1, you can also use +-v <n>+ (where <n> is the
468 ---------------------
469 $ git format-patch -v4 -M -s -o outgoing origin/master
470 ---------------------
473 superseded in http://patchwork.buildroot.org[patchwork]. You need to
474 create an account on http://patchwork.buildroot.org[patchwork] to be
477 address you register in http://patchwork.buildroot.org[patchwork] should
480 You can also add the +--in-reply-to <message-id>+ option when
483 http://patchwork.buildroot.org[patchwork].  The advantage of
484 *in-reply-to* is that patchwork will automatically mark the previous
487 [[reporting-bugs]]
491 xref:community-resources[the mailing list archive] whether someone has
495 opening a bug in the xref:community-resources[bug tracker] or by
496 xref:community-resources[sending a mail to the mailing list], there are
506 * version of Buildroot
513 +defconfig+; see xref:customize-store-buildroot-config[]).
517 preserve Unix-style line terminators when downloading raw pastes.
519 - https://gist.github.com/
520 - http://code.bulix.org/
524 Buildroot includes a run-time testing framework built upon Python
528 * build a well defined Buildroot configuration
534 +support/testing/run-tests+ tool, which has a series of options
535 documented in the tool's help '-h' description. Some common options
542 cases can be listed by executing +support/testing/run-tests -l+. These tests
546 ---------------------
547 $ support/testing/run-tests -l
573 ---------------------
577 ---------------------
578 $ support/testing/run-tests -d dl -o output_folder -k tests.init.test_busybox.TestInitSystemBusybox…
587 ---------------------
591 unless the option +-k+ is passed to *keep* the output directory.
595 Within the Buildroot repository, the testing framework is organized at the
605 that use things like nested +br2-external+ folders to provide
612 * Defining the +config+ member of the test class, to the Buildroot
641 ---------------------
644 TestInitSystemBusyboxRw-build.log
645 TestInitSystemBusyboxRw-run.log
646 ---------------------
648 +TestInitSystemBusyboxRw/+ is the Buildroot output directory, and it
649 is preserved only if the +-k+ option is passed.
651 +TestInitSystemBusyboxRw-build.log+ is the log of the Buildroot build.
653 +TestInitSystemBusyboxRw-run.log+ is the log of the Qemu boot and
658 result, the first few lines of +TestInitSystemBusyboxRw-run.log+
663 Buildroot make targets (in order to regenerate the complete image with
668 All runtime tests are regularly executed by Buildroot Gitlab CI
670 https://gitlab.com/buildroot.org/buildroot/-/jobs.
673 existing tests continue to work after making changes in Buildroot.
675 In order to achieve this, you need to create a fork of the Buildroot
676 project on Gitlab, and be able to push branches to your Buildroot fork
680 pipeline will be triggered or not, and for which test cases.
685 * To trigger all run-test test case jobs, push a branch that ends with
686   +-runtime-tests+:
688 ---------------------
689  $ git push gitlab HEAD:<name>-runtime-tests
690 ---------------------
697 ---------------------
698  $ git push gitlab HEAD:<name>-<test case name>
699 ---------------------
703 ---------------------
704  $ git push gitlab HEAD:foo-tests.init.test_busybox.TestInitSystemBusyboxRo
705 ---------------------
709 ---------------------
710  $ git push gitlab HEAD:foo-tests.init.test_busybox
711  $ git push gitlab HEAD:foo-tests.init
712 ---------------------