| // -*- mode:doc; -*- |
| // vim: set syntax=asciidoc: |
| |
| Contributing to Buildroot |
| ======================== |
| |
| If you want to contribute to Buildroot, you will need a git view of |
| the project. Refer to xref:getting-buildroot[] to get it. |
| |
| Currently, the mailing list is the central place for contribution. |
| If you have not already subscribed to it, then refer to |
| xref:mailing-list-subscribe[]. |
| |
| Recently, a web interface is also used to manage patches sent to the |
| mailing list, see xref:patchwork[]. |
| |
| [NOTE] |
| _Please, do not attach patches to bugs, send them to the mailing list |
| instead_ (see xref:submitting-patches[]). |
| |
| [[submitting-patches]] |
| Submitting patches |
| ------------------ |
| |
| When your changes are done, and committed in your local git view, |
| _rebase_ your development branch on top of the upstream tree before |
| generating the patch set. To do so, run: |
| |
| --------------------- |
| $ git fetch --all --tags |
| $ git rebase origin/master |
| --------------------- |
| |
| Here, 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@busybox.net outgoing/* |
| --------------------- |
| |
| Note that +git+ should be configured to use your mail account. |
| To configure +git+, see +man git-send-email+ or google it. |
| |
| 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, |
| use +git send-email+ to send your patches. |
| |
| 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, the changelog may be added in the cover letter rather than in |
| the individual commits. |
| |
| 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 less than 80-character length |
| |
| Some more paragraph giving some more details. |
| |
| And yet another paragraph giving more details. |
| |
| Signed-off-by: John Doe <john.doe@noname.org> |
| --- |
| 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 -o outgoing origin/master |
| --------------------- |
| |
| Reviewing/Testing patches |
| ------------------------- |
| |
| The review process for new patches is done over the mailing list. Once |
| a patch is submitted to the mailing list, other developers will provide |
| feedback to the patch via emails sent through the mailing list. |
| |
| 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. |
| |
| Some tags are used to help following the state of any patch posted on |
| the mailing-list: |
| |
| Acked-by:: Indicates that the patch can be committed. |
| |
| Tested-by:: Indicates that the patch has been tested. It is useful |
| but not necessary to add a comment about what has been tested. |
| |
| 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. |
| |
| Autobuild |
| --------- |
| |
| The Buildroot community is currently setting up automatic builds in |
| order to test more and more configurations. All build results are |
| available at http://autobuild.buildroot.org[] |
| |
| A good way to contribute is by fixing broken builds. |
| |
| In the commit message of a patch fixing an _autobuild_, add a |
| reference to the _build result directory_ (the +dir+ link in the _data |
| column_): |
| |
| --------------------- |
| Fixes http://autobuild.buildroot.org/results/51000a9d4656afe9e0ea6f07b9f8ed374c2e4069 |
| --------------------- |
| |
| [[reporting-bugs]] |
| Reporting issues/bugs, get help |
| ------------------------------- |
| |
| Before reporting any issue, please check |
| xref:mailing-list-subscribe[the mailing list archive] in case someone has |
| already reported and fixed a similar problem. |
| |
| However you choose to report bugs or get help, |
| xref:bugtracker[opening a bug] or |
| xref:mailing-list-subscribe[send 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) which the build fails |
| * the command that fails and its output |
| * any information you think that may be relevant |
| |
| Additionnally, your can add the +.config+ file. |
| |
| If some of these details are too large, do not hesitate to use a |
| pastebin service (see http://www.similarsitesearch.com/alternatives-to/pastebin.com[]). |