docs/manual/contribute.txt

1 // -*- mode:doc; -*-
17 xref:community-resources[] for the subscription link.
22 send your patches to the mailing list. Refer to xref:getting-buildroot[]
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]
69     xref:submitting-patches[]). In case you created a patch against the
75 ---------------------
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
142 purposes. Please see xref:apply-patches-patchwork[] for more
145 [[apply-patches-patchwork]]
156 ---------------------
157 $ git checkout -b <test-branch-name>
158 $ wget -O - <mbox-url> | git am
159 ---------------------
177 [[submitting-patches]]
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
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 ---------------------
297 Now, you are ready to generate then submit your patch set.
299 To generate it, run:
301 ---------------------
302 $ git format-patch -M -n -s -o outgoing origin/master
303 ---------------------
305 This will generate patch files in the +outgoing+ subdirectory,
306 automatically adding the +Signed-off-by+ line.
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 ---------------------
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.
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 ---------------------
480 You can also add the +--in-reply-to <message-id>+ option when
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
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
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.
605 that use things like nested +br2-external+ folders to provide
641 ---------------------
644 TestInitSystemBusyboxRw-build.log
645 TestInitSystemBusyboxRw-run.log
646 ---------------------
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+
666 ==== Runtime tests and Gitlab CI
668 All runtime tests are regularly executed by Buildroot Gitlab CI
669 infrastructure, see .gitlab.yml and
670 https://gitlab.com/buildroot.org/buildroot/-/jobs.
672 You can also use Gitlab CI to test your new test cases, or verify that
676 project on Gitlab, and be able to push branches to your Buildroot fork
677 on Gitlab.
679 The name of the branch that you push will determine if a Gitlab CI
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 ---------------------