docs/manual/contribute.txt

1 // -*- mode:doc; -*-
17 xref:community-resources[] for the subscription link.
19 If you are going to touch the code, it is highly recommended to use a
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 ---------------------
301 ---------------------
302 $ git format-patch -M -n -s -o outgoing origin/master
303 ---------------------
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.
367 * deep impact of the changes in the rest of the project;
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+
670 https://gitlab.com/buildroot.org/buildroot/-/jobs.
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 ---------------------