2012-11-11 04:14:53 +01:00
|
|
|
// -*- mode:doc; -*-
|
2013-02-13 13:59:02 +01:00
|
|
|
// vim: set syntax=asciidoc:
|
2012-11-11 04:14:53 +01:00
|
|
|
|
manual: use one-line titles instead of two-line titles (trivial)
Asciidoc supports two syntaxes for section titles: two-line titles (title
plus underline consisting of a particular symbol), and one-line titles
(title prefixed with a specific number of = signs).
The two-line title underlines are:
Level 0 (top level): ======================
Level 1: ----------------------
Level 2: ~~~~~~~~~~~~~~~~~~~~~~
Level 3: ^^^^^^^^^^^^^^^^^^^^^^
Level 4 (bottom level): ++++++++++++++++++++++
and the one-line title prefixes:
= Document Title (level 0) =
== Section title (level 1) ==
=== Section title (level 2) ===
==== Section title (level 3) ====
===== Section title (level 4) =====
The buildroot manual is currenly using the two-line titles, but this has
multiple disadvantages:
- asciidoc also uses some of the underline symbols for other purposes (like
preformatted code, example blocks, ...), which makes it difficult to do
mass replacements, such as a planned follow-up patch that needs to move
all sections one level down.
- it is difficult to remember which level a given underline symbol (=-~^+)
corresponds to, while counting = signs is easy.
This patch changes all two-level titles to one-level titles in the manual.
The bulk of the change was done with the following Python script, except for
the level 1 titles (-----) as these underlines are also used for literal
code blocks.
This patch only changes the titles, no other changes. In
adding-packages-directory.txt, I did add missing newlines between some
titles and their content.
----------------------------------------------------------------------------
#!/usr/bin/env python
import sys
import mmap
import re
for input in sys.argv[1:]:
f = open(input, 'r+')
f.flush()
s = mmap.mmap(f.fileno(), 0)
# Level 0 (top level): ====================== =
# Level 1: ---------------------- ==
# Level 2: ~~~~~~~~~~~~~~~~~~~~~~ ===
# Level 3: ^^^^^^^^^^^^^^^^^^^^^^ ====
# Level 4 (bottom level): ++++++++++++++++++++++ =====
def replace_title(s, symbol, replacement):
pattern = re.compile(r'(.+\n)\%s{2,}\n' % symbol, re.MULTILINE)
return pattern.sub(r'%s \1' % replacement, s)
new = s
new = replace_title(new, '=', '=')
new = replace_title(new, '+', '=====')
new = replace_title(new, '^', '====')
new = replace_title(new, '~', '===')
#new = replace_title(new, '-', '==')
s.seek(0)
s.write(new)
s.resize(s.tell())
s.close()
f.close()
----------------------------------------------------------------------------
Signed-off-by: Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
Signed-off-by: Peter Korsgaard <peter@korsgaard.com>
2014-05-02 07:47:30 +02:00
|
|
|
= Contributing to Buildroot
|
2014-03-05 17:24:27 +01:00
|
|
|
|
|
|
|
|
There are many ways in which you can contribute to Buildroot: analyzing
|
|
|
|
|
and fixing bugs, analyzing and fixing package build failures detected by
|
|
|
|
|
the autobuilders, testing and reviewing patches sent by other
|
|
|
|
|
developers, working on the items in our TODO list and sending your own
|
|
|
|
|
improvements to Buildroot or its manual. The following sections give a
|
|
|
|
|
little more detail on each of these items.
|
|
|
|
|
|
|
|
|
|
If you are interested in contributing to Buildroot, the first thing you
|
|
|
|
|
should do is to subscribe to the Buildroot mailing list. This list is
|
|
|
|
|
the main way of interacting with other Buildroot developers and to send
|
|
|
|
|
contributions to. If you aren't subscribed yet, then refer to
|
2012-11-11 04:14:53 +01:00
|
|
|
xref:mailing-list-subscribe[].
|
|
|
|
|
|
2014-03-05 17:24:27 +01:00
|
|
|
If you are going to touch the code, it is highly recommended to use a
|
|
|
|
|
git repository of Buildroot, rather than starting from an extracted
|
|
|
|
|
source code tarball. Git is the easiest way to develop from and directly
|
|
|
|
|
send your patches to the mailing list. Refer to xref:getting-buildroot[]
|
|
|
|
|
for more information on obtaining a Buildroot git tree.
|
2012-11-11 04:14:53 +01:00
|
|
|
|
manual: use one-line titles instead of two-line titles (trivial)
Asciidoc supports two syntaxes for section titles: two-line titles (title
plus underline consisting of a particular symbol), and one-line titles
(title prefixed with a specific number of = signs).
The two-line title underlines are:
Level 0 (top level): ======================
Level 1: ----------------------
Level 2: ~~~~~~~~~~~~~~~~~~~~~~
Level 3: ^^^^^^^^^^^^^^^^^^^^^^
Level 4 (bottom level): ++++++++++++++++++++++
and the one-line title prefixes:
= Document Title (level 0) =
== Section title (level 1) ==
=== Section title (level 2) ===
==== Section title (level 3) ====
===== Section title (level 4) =====
The buildroot manual is currenly using the two-line titles, but this has
multiple disadvantages:
- asciidoc also uses some of the underline symbols for other purposes (like
preformatted code, example blocks, ...), which makes it difficult to do
mass replacements, such as a planned follow-up patch that needs to move
all sections one level down.
- it is difficult to remember which level a given underline symbol (=-~^+)
corresponds to, while counting = signs is easy.
This patch changes all two-level titles to one-level titles in the manual.
The bulk of the change was done with the following Python script, except for
the level 1 titles (-----) as these underlines are also used for literal
code blocks.
This patch only changes the titles, no other changes. In
adding-packages-directory.txt, I did add missing newlines between some
titles and their content.
----------------------------------------------------------------------------
#!/usr/bin/env python
import sys
import mmap
import re
for input in sys.argv[1:]:
f = open(input, 'r+')
f.flush()
s = mmap.mmap(f.fileno(), 0)
# Level 0 (top level): ====================== =
# Level 1: ---------------------- ==
# Level 2: ~~~~~~~~~~~~~~~~~~~~~~ ===
# Level 3: ^^^^^^^^^^^^^^^^^^^^^^ ====
# Level 4 (bottom level): ++++++++++++++++++++++ =====
def replace_title(s, symbol, replacement):
pattern = re.compile(r'(.+\n)\%s{2,}\n' % symbol, re.MULTILINE)
return pattern.sub(r'%s \1' % replacement, s)
new = s
new = replace_title(new, '=', '=')
new = replace_title(new, '+', '=====')
new = replace_title(new, '^', '====')
new = replace_title(new, '~', '===')
#new = replace_title(new, '-', '==')
s.seek(0)
s.write(new)
s.resize(s.tell())
s.close()
f.close()
----------------------------------------------------------------------------
Signed-off-by: Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
Signed-off-by: Peter Korsgaard <peter@korsgaard.com>
2014-05-02 07:47:30 +02:00
|
|
|
== Reproducing, analyzing and fixing bugs
|
2014-03-05 17:24:28 +01:00
|
|
|
|
|
|
|
|
A first way of contributing is to have a look at the open bug reports in
|
|
|
|
|
the https://bugs.busybox.net/buglist.cgi?product=buildroot[Buildroot bug
|
|
|
|
|
tracker]. As we strive to keep the bug count as small as possible, all
|
|
|
|
|
help in reproducing, analyzing and fixing reported bugs is more than
|
|
|
|
|
welcome. Don't hesitate to add a comment to bug reports reporting your
|
|
|
|
|
findings, even if you don't yet see the full picture.
|
|
|
|
|
|
manual: use one-line titles instead of two-line titles (trivial)
Asciidoc supports two syntaxes for section titles: two-line titles (title
plus underline consisting of a particular symbol), and one-line titles
(title prefixed with a specific number of = signs).
The two-line title underlines are:
Level 0 (top level): ======================
Level 1: ----------------------
Level 2: ~~~~~~~~~~~~~~~~~~~~~~
Level 3: ^^^^^^^^^^^^^^^^^^^^^^
Level 4 (bottom level): ++++++++++++++++++++++
and the one-line title prefixes:
= Document Title (level 0) =
== Section title (level 1) ==
=== Section title (level 2) ===
==== Section title (level 3) ====
===== Section title (level 4) =====
The buildroot manual is currenly using the two-line titles, but this has
multiple disadvantages:
- asciidoc also uses some of the underline symbols for other purposes (like
preformatted code, example blocks, ...), which makes it difficult to do
mass replacements, such as a planned follow-up patch that needs to move
all sections one level down.
- it is difficult to remember which level a given underline symbol (=-~^+)
corresponds to, while counting = signs is easy.
This patch changes all two-level titles to one-level titles in the manual.
The bulk of the change was done with the following Python script, except for
the level 1 titles (-----) as these underlines are also used for literal
code blocks.
This patch only changes the titles, no other changes. In
adding-packages-directory.txt, I did add missing newlines between some
titles and their content.
----------------------------------------------------------------------------
#!/usr/bin/env python
import sys
import mmap
import re
for input in sys.argv[1:]:
f = open(input, 'r+')
f.flush()
s = mmap.mmap(f.fileno(), 0)
# Level 0 (top level): ====================== =
# Level 1: ---------------------- ==
# Level 2: ~~~~~~~~~~~~~~~~~~~~~~ ===
# Level 3: ^^^^^^^^^^^^^^^^^^^^^^ ====
# Level 4 (bottom level): ++++++++++++++++++++++ =====
def replace_title(s, symbol, replacement):
pattern = re.compile(r'(.+\n)\%s{2,}\n' % symbol, re.MULTILINE)
return pattern.sub(r'%s \1' % replacement, s)
new = s
new = replace_title(new, '=', '=')
new = replace_title(new, '+', '=====')
new = replace_title(new, '^', '====')
new = replace_title(new, '~', '===')
#new = replace_title(new, '-', '==')
s.seek(0)
s.write(new)
s.resize(s.tell())
s.close()
f.close()
----------------------------------------------------------------------------
Signed-off-by: Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
Signed-off-by: Peter Korsgaard <peter@korsgaard.com>
2014-05-02 07:47:30 +02:00
|
|
|
== Analyzing and fixing autobuild failures
|
2014-03-06 11:07:29 +01:00
|
|
|
|
|
|
|
|
The Buildroot autobuilders are a set of build machines that continuously
|
|
|
|
|
run Buildroot builds based on random configurations. This is done for
|
|
|
|
|
all architectures supported by Buildroot, with various toolchains, and
|
|
|
|
|
with a random selection of packages. With the large commit activity on
|
|
|
|
|
Buildroot, these autobuilders are a great help in detecting problems
|
|
|
|
|
very early after commit.
|
|
|
|
|
|
|
|
|
|
All build results are available at http://autobuild.buildroot.org[],
|
|
|
|
|
statistics are at http://autobuild.buildroot.org/stats.php[]. Every day,
|
|
|
|
|
an overview of all failed packages is sent to the mailing list.
|
|
|
|
|
|
|
|
|
|
Detecting problems is great, but obviously these problems have to be
|
|
|
|
|
fixed as well. Your contribution is very welcome here! There are
|
|
|
|
|
basically two things that can be done:
|
|
|
|
|
|
|
|
|
|
- Analyzing the problems. The daily summary mails do not contain details
|
|
|
|
|
about the actual failures: in order to see what's going on you have to
|
|
|
|
|
open the build log and check the last output. Having someone doing
|
|
|
|
|
this for all packages in the mail is very useful for other developers,
|
|
|
|
|
as they can make a quick initial analysis based on this output alone.
|
|
|
|
|
|
|
|
|
|
- Fixing a problem. When fixing autobuild failures, you should follow
|
|
|
|
|
these steps:
|
|
|
|
|
. Check if you can reproduce the problem by building with the same
|
|
|
|
|
configuration. You can do this manually, or use the
|
|
|
|
|
http://git.buildroot.org/buildroot-test/tree/utils/br-reproduce-build[br-reproduce-build]
|
|
|
|
|
script that will automatically clone a Buildroot git repository,
|
|
|
|
|
checkout the correct revision, download and set the right
|
|
|
|
|
configuration, and start the build.
|
|
|
|
|
. Analyze the problem and create a fix.
|
|
|
|
|
. Verify that the problem is really fixed by starting from a clean
|
|
|
|
|
Buildroot tree and only applying your fix.
|
|
|
|
|
. Send the fix to the Buildroot mailing list (see
|
|
|
|
|
xref:submitting-patches[]). In case you created a patch against the
|
|
|
|
|
package sources, you should also send the patch upstream so that the
|
|
|
|
|
problem will be fixed in a later release, and the patch in Buildroot
|
|
|
|
|
can be removed.
|
|
|
|
|
In the commit message of a patch fixing an autobuild failure, add a
|
|
|
|
|
reference to the build result directory, as follows:
|
|
|
|
|
---------------------
|
|
|
|
|
Fixes http://autobuild.buildroot.org/results/51000a9d4656afe9e0ea6f07b9f8ed374c2e4069
|
|
|
|
|
---------------------
|
|
|
|
|
|
manual: use one-line titles instead of two-line titles (trivial)
Asciidoc supports two syntaxes for section titles: two-line titles (title
plus underline consisting of a particular symbol), and one-line titles
(title prefixed with a specific number of = signs).
The two-line title underlines are:
Level 0 (top level): ======================
Level 1: ----------------------
Level 2: ~~~~~~~~~~~~~~~~~~~~~~
Level 3: ^^^^^^^^^^^^^^^^^^^^^^
Level 4 (bottom level): ++++++++++++++++++++++
and the one-line title prefixes:
= Document Title (level 0) =
== Section title (level 1) ==
=== Section title (level 2) ===
==== Section title (level 3) ====
===== Section title (level 4) =====
The buildroot manual is currenly using the two-line titles, but this has
multiple disadvantages:
- asciidoc also uses some of the underline symbols for other purposes (like
preformatted code, example blocks, ...), which makes it difficult to do
mass replacements, such as a planned follow-up patch that needs to move
all sections one level down.
- it is difficult to remember which level a given underline symbol (=-~^+)
corresponds to, while counting = signs is easy.
This patch changes all two-level titles to one-level titles in the manual.
The bulk of the change was done with the following Python script, except for
the level 1 titles (-----) as these underlines are also used for literal
code blocks.
This patch only changes the titles, no other changes. In
adding-packages-directory.txt, I did add missing newlines between some
titles and their content.
----------------------------------------------------------------------------
#!/usr/bin/env python
import sys
import mmap
import re
for input in sys.argv[1:]:
f = open(input, 'r+')
f.flush()
s = mmap.mmap(f.fileno(), 0)
# Level 0 (top level): ====================== =
# Level 1: ---------------------- ==
# Level 2: ~~~~~~~~~~~~~~~~~~~~~~ ===
# Level 3: ^^^^^^^^^^^^^^^^^^^^^^ ====
# Level 4 (bottom level): ++++++++++++++++++++++ =====
def replace_title(s, symbol, replacement):
pattern = re.compile(r'(.+\n)\%s{2,}\n' % symbol, re.MULTILINE)
return pattern.sub(r'%s \1' % replacement, s)
new = s
new = replace_title(new, '=', '=')
new = replace_title(new, '+', '=====')
new = replace_title(new, '^', '====')
new = replace_title(new, '~', '===')
#new = replace_title(new, '-', '==')
s.seek(0)
s.write(new)
s.resize(s.tell())
s.close()
f.close()
----------------------------------------------------------------------------
Signed-off-by: Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
Signed-off-by: Peter Korsgaard <peter@korsgaard.com>
2014-05-02 07:47:30 +02:00
|
|
|
== Reviewing and testing patches
|
2014-03-06 11:07:30 +01:00
|
|
|
|
|
|
|
|
With the amount of patches sent to the mailing list each day, the
|
|
|
|
|
maintainer has a very hard job to judge which patches are ready to apply
|
|
|
|
|
and which ones aren't. Contributors can greatly help here by reviewing
|
|
|
|
|
and testing these patches.
|
|
|
|
|
|
|
|
|
|
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.
|
|
|
|
|
|
|
|
|
|
To indicate approval of a patch, there are three formal tags that keep
|
|
|
|
|
track of this approval. To add your tag to a patch, reply to it with the
|
|
|
|
|
approval tag below the original author's Signed-off-by line. These tags
|
|
|
|
|
will be picked up automatically by patchwork (see
|
2014-03-28 22:24:45 +01:00
|
|
|
xref:apply-patches-patchwork[]) and will be part of the commit log when
|
2014-03-06 11:07:30 +01:00
|
|
|
the patch is accepted.
|
|
|
|
|
|
|
|
|
|
Tested-by:: Indicates that the patch has been tested successfully.
|
|
|
|
|
You are encouraged to specify what kind of testing you performed
|
|
|
|
|
(compile-test on architecture X and Y, runtime test on target A,
|
|
|
|
|
...). This additional information helps other testers and the
|
|
|
|
|
maintainer.
|
|
|
|
|
|
|
|
|
|
Reviewed-by:: Indicates that you code-reviewed the patch and did your
|
|
|
|
|
best in spotting problems, but you are not sufficiently familiar with
|
|
|
|
|
the area touched to provide an Acked-by tag. This means that there
|
|
|
|
|
may be remaining problems in the patch that would be spotted by
|
|
|
|
|
someone with more experience in that area. Should such problems be
|
|
|
|
|
detected, your Reviewed-by tag remains appropriate and you cannot
|
|
|
|
|
be blamed.
|
|
|
|
|
|
|
|
|
|
Acked-by:: Indicates that you code-reviewed the patch and you are
|
|
|
|
|
familiar enough with the area touched to feel that the patch can be
|
|
|
|
|
committed as-is (no additional changes required). In case it later
|
|
|
|
|
turns out that something is wrong with the patch, your Acked-by could
|
|
|
|
|
be considered inappropriate. The difference between Acked-by and
|
|
|
|
|
Reviewed-by is thus mainly that you are prepared to take the blame on
|
|
|
|
|
Acked patches, but not on Reviewed ones.
|
|
|
|
|
|
|
|
|
|
If you reviewed a patch and have comments on it, you should simply reply
|
|
|
|
|
to the patch stating these comments, without providing a Reviewed-by or
|
|
|
|
|
Acked-by tag. These tags should only be provided if you judge the patch
|
|
|
|
|
to be good as it is.
|
|
|
|
|
|
|
|
|
|
It is important to note that neither Reviewed-by nor Acked-by imply
|
|
|
|
|
that testing has been performed. To indicate that you both reviewed and
|
|
|
|
|
tested the patch, provide two separate tags (Reviewed/Acked-by and
|
|
|
|
|
Tested-by).
|
|
|
|
|
|
|
|
|
|
Note also that _any developer_ can provide Tested/Reviewed/Acked-by
|
|
|
|
|
tags, without exception, and we encourage everyone to do this. Buildroot
|
|
|
|
|
does not have a defined group of _core_ developers, it just so happens
|
|
|
|
|
that some developers are more active than others. The maintainer will
|
|
|
|
|
value tags according to the track record of their submitter. Tags
|
|
|
|
|
provided by a regular contributor will naturally be trusted more than
|
|
|
|
|
tags provided by a newcomer. As you provide tags more regularly, your
|
|
|
|
|
'trustworthiness' (in the eyes of the maintainer) will go up, but _any_
|
|
|
|
|
tag provided is valuable.
|
|
|
|
|
|
|
|
|
|
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.
|
|
|
|
|
|
manual: use one-line titles instead of two-line titles (trivial)
Asciidoc supports two syntaxes for section titles: two-line titles (title
plus underline consisting of a particular symbol), and one-line titles
(title prefixed with a specific number of = signs).
The two-line title underlines are:
Level 0 (top level): ======================
Level 1: ----------------------
Level 2: ~~~~~~~~~~~~~~~~~~~~~~
Level 3: ^^^^^^^^^^^^^^^^^^^^^^
Level 4 (bottom level): ++++++++++++++++++++++
and the one-line title prefixes:
= Document Title (level 0) =
== Section title (level 1) ==
=== Section title (level 2) ===
==== Section title (level 3) ====
===== Section title (level 4) =====
The buildroot manual is currenly using the two-line titles, but this has
multiple disadvantages:
- asciidoc also uses some of the underline symbols for other purposes (like
preformatted code, example blocks, ...), which makes it difficult to do
mass replacements, such as a planned follow-up patch that needs to move
all sections one level down.
- it is difficult to remember which level a given underline symbol (=-~^+)
corresponds to, while counting = signs is easy.
This patch changes all two-level titles to one-level titles in the manual.
The bulk of the change was done with the following Python script, except for
the level 1 titles (-----) as these underlines are also used for literal
code blocks.
This patch only changes the titles, no other changes. In
adding-packages-directory.txt, I did add missing newlines between some
titles and their content.
----------------------------------------------------------------------------
#!/usr/bin/env python
import sys
import mmap
import re
for input in sys.argv[1:]:
f = open(input, 'r+')
f.flush()
s = mmap.mmap(f.fileno(), 0)
# Level 0 (top level): ====================== =
# Level 1: ---------------------- ==
# Level 2: ~~~~~~~~~~~~~~~~~~~~~~ ===
# Level 3: ^^^^^^^^^^^^^^^^^^^^^^ ====
# Level 4 (bottom level): ++++++++++++++++++++++ =====
def replace_title(s, symbol, replacement):
pattern = re.compile(r'(.+\n)\%s{2,}\n' % symbol, re.MULTILINE)
return pattern.sub(r'%s \1' % replacement, s)
new = s
new = replace_title(new, '=', '=')
new = replace_title(new, '+', '=====')
new = replace_title(new, '^', '====')
new = replace_title(new, '~', '===')
#new = replace_title(new, '-', '==')
s.seek(0)
s.write(new)
s.resize(s.tell())
s.close()
f.close()
----------------------------------------------------------------------------
Signed-off-by: Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
Signed-off-by: Peter Korsgaard <peter@korsgaard.com>
2014-05-02 07:47:30 +02:00
|
|
|
== Work on items from the TODO list
|
2014-03-06 11:07:31 +01:00
|
|
|
|
|
|
|
|
If you want to contribute to Buildroot but don't know where to start,
|
|
|
|
|
and you don't like any of the above topics, you can always work on items
|
|
|
|
|
from the http://elinux.org/Buildroot#Todo_list[Buildroot TODO list].
|
|
|
|
|
Don't hesitate to discuss an item first on the mailing list or on IRC.
|
|
|
|
|
Do edit the wiki to indicate when you start working on an item, so we
|
|
|
|
|
avoid duplicate efforts.
|
2014-03-06 11:07:30 +01:00
|
|
|
|
2012-11-11 04:14:53 +01:00
|
|
|
[[submitting-patches]]
|
manual: use one-line titles instead of two-line titles (trivial)
Asciidoc supports two syntaxes for section titles: two-line titles (title
plus underline consisting of a particular symbol), and one-line titles
(title prefixed with a specific number of = signs).
The two-line title underlines are:
Level 0 (top level): ======================
Level 1: ----------------------
Level 2: ~~~~~~~~~~~~~~~~~~~~~~
Level 3: ^^^^^^^^^^^^^^^^^^^^^^
Level 4 (bottom level): ++++++++++++++++++++++
and the one-line title prefixes:
= Document Title (level 0) =
== Section title (level 1) ==
=== Section title (level 2) ===
==== Section title (level 3) ====
===== Section title (level 4) =====
The buildroot manual is currenly using the two-line titles, but this has
multiple disadvantages:
- asciidoc also uses some of the underline symbols for other purposes (like
preformatted code, example blocks, ...), which makes it difficult to do
mass replacements, such as a planned follow-up patch that needs to move
all sections one level down.
- it is difficult to remember which level a given underline symbol (=-~^+)
corresponds to, while counting = signs is easy.
This patch changes all two-level titles to one-level titles in the manual.
The bulk of the change was done with the following Python script, except for
the level 1 titles (-----) as these underlines are also used for literal
code blocks.
This patch only changes the titles, no other changes. In
adding-packages-directory.txt, I did add missing newlines between some
titles and their content.
----------------------------------------------------------------------------
#!/usr/bin/env python
import sys
import mmap
import re
for input in sys.argv[1:]:
f = open(input, 'r+')
f.flush()
s = mmap.mmap(f.fileno(), 0)
# Level 0 (top level): ====================== =
# Level 1: ---------------------- ==
# Level 2: ~~~~~~~~~~~~~~~~~~~~~~ ===
# Level 3: ^^^^^^^^^^^^^^^^^^^^^^ ====
# Level 4 (bottom level): ++++++++++++++++++++++ =====
def replace_title(s, symbol, replacement):
pattern = re.compile(r'(.+\n)\%s{2,}\n' % symbol, re.MULTILINE)
return pattern.sub(r'%s \1' % replacement, s)
new = s
new = replace_title(new, '=', '=')
new = replace_title(new, '+', '=====')
new = replace_title(new, '^', '====')
new = replace_title(new, '~', '===')
#new = replace_title(new, '-', '==')
s.seek(0)
s.write(new)
s.resize(s.tell())
s.close()
f.close()
----------------------------------------------------------------------------
Signed-off-by: Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
Signed-off-by: Peter Korsgaard <peter@korsgaard.com>
2014-05-02 07:47:30 +02:00
|
|
|
== Submitting patches
|
2012-11-11 04:14:53 +01:00
|
|
|
|
2014-03-05 17:24:27 +01:00
|
|
|
[NOTE]
|
|
|
|
|
_Please, do not attach patches to bugs, send them to the mailing list
|
|
|
|
|
instead_.
|
|
|
|
|
|
2014-03-06 11:07:32 +01:00
|
|
|
If you made some changes to Buildroot and you would like to contribute
|
|
|
|
|
them to the Buildroot project, proceed as follows. Starting from the
|
|
|
|
|
changes committed in your local git view, _rebase_ your development
|
|
|
|
|
branch on top of the upstream tree before generating a patch set. To do
|
|
|
|
|
so, run:
|
2012-11-11 04:14:53 +01:00
|
|
|
|
|
|
|
|
---------------------
|
2013-08-09 12:16:48 +02:00
|
|
|
$ git fetch --all --tags
|
|
|
|
|
$ git rebase origin/master
|
2012-11-11 04:14:53 +01:00
|
|
|
---------------------
|
|
|
|
|
|
2014-03-06 11:07:32 +01:00
|
|
|
Now, you are ready to generate then submit your patch set.
|
2012-11-11 04:14:53 +01:00
|
|
|
|
|
|
|
|
To generate it, run:
|
|
|
|
|
|
|
|
|
|
---------------------
|
2013-08-09 12:16:48 +02:00
|
|
|
$ git format-patch -M -n -s -o outgoing origin/master
|
2012-11-11 04:14:53 +01:00
|
|
|
---------------------
|
|
|
|
|
|
|
|
|
|
This will generate patch files in the +outgoing+ subdirectory,
|
2013-09-16 15:07:28 +02:00
|
|
|
automatically adding the +Signed-off-by+ line.
|
2012-11-11 04:14:53 +01:00
|
|
|
|
|
|
|
|
Once patch files are generated, you can review/edit the commit message
|
2014-03-06 11:07:32 +01:00
|
|
|
before submitting them, using your favorite text editor.
|
2012-11-11 04:14:53 +01:00
|
|
|
|
|
|
|
|
Lastly, send/submit your patch set to the Buildroot mailing list:
|
|
|
|
|
|
|
|
|
|
---------------------
|
2014-02-12 17:54:57 +01:00
|
|
|
$ git send-email --to buildroot@buildroot.org outgoing/*
|
2012-11-11 04:14:53 +01:00
|
|
|
---------------------
|
|
|
|
|
|
|
|
|
|
Note that +git+ should be configured to use your mail account.
|
|
|
|
|
To configure +git+, see +man git-send-email+ or google it.
|
|
|
|
|
|
2014-03-06 11:07:32 +01:00
|
|
|
If you do not use +git send-email+, 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 yet, learn to use +git send-email+.
|
2012-11-11 04:14:53 +01:00
|
|
|
|
manual: use one-line titles instead of two-line titles (trivial)
Asciidoc supports two syntaxes for section titles: two-line titles (title
plus underline consisting of a particular symbol), and one-line titles
(title prefixed with a specific number of = signs).
The two-line title underlines are:
Level 0 (top level): ======================
Level 1: ----------------------
Level 2: ~~~~~~~~~~~~~~~~~~~~~~
Level 3: ^^^^^^^^^^^^^^^^^^^^^^
Level 4 (bottom level): ++++++++++++++++++++++
and the one-line title prefixes:
= Document Title (level 0) =
== Section title (level 1) ==
=== Section title (level 2) ===
==== Section title (level 3) ====
===== Section title (level 4) =====
The buildroot manual is currenly using the two-line titles, but this has
multiple disadvantages:
- asciidoc also uses some of the underline symbols for other purposes (like
preformatted code, example blocks, ...), which makes it difficult to do
mass replacements, such as a planned follow-up patch that needs to move
all sections one level down.
- it is difficult to remember which level a given underline symbol (=-~^+)
corresponds to, while counting = signs is easy.
This patch changes all two-level titles to one-level titles in the manual.
The bulk of the change was done with the following Python script, except for
the level 1 titles (-----) as these underlines are also used for literal
code blocks.
This patch only changes the titles, no other changes. In
adding-packages-directory.txt, I did add missing newlines between some
titles and their content.
----------------------------------------------------------------------------
#!/usr/bin/env python
import sys
import mmap
import re
for input in sys.argv[1:]:
f = open(input, 'r+')
f.flush()
s = mmap.mmap(f.fileno(), 0)
# Level 0 (top level): ====================== =
# Level 1: ---------------------- ==
# Level 2: ~~~~~~~~~~~~~~~~~~~~~~ ===
# Level 3: ^^^^^^^^^^^^^^^^^^^^^^ ====
# Level 4 (bottom level): ++++++++++++++++++++++ =====
def replace_title(s, symbol, replacement):
pattern = re.compile(r'(.+\n)\%s{2,}\n' % symbol, re.MULTILINE)
return pattern.sub(r'%s \1' % replacement, s)
new = s
new = replace_title(new, '=', '=')
new = replace_title(new, '+', '=====')
new = replace_title(new, '^', '====')
new = replace_title(new, '~', '===')
#new = replace_title(new, '-', '==')
s.seek(0)
s.write(new)
s.resize(s.tell())
s.close()
f.close()
----------------------------------------------------------------------------
Signed-off-by: Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
Signed-off-by: Peter Korsgaard <peter@korsgaard.com>
2014-05-02 07:47:30 +02:00
|
|
|
=== Cover letter
|
2013-08-09 12:16:46 +02:00
|
|
|
|
|
|
|
|
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.
|
|
|
|
|
|
manual: use one-line titles instead of two-line titles (trivial)
Asciidoc supports two syntaxes for section titles: two-line titles (title
plus underline consisting of a particular symbol), and one-line titles
(title prefixed with a specific number of = signs).
The two-line title underlines are:
Level 0 (top level): ======================
Level 1: ----------------------
Level 2: ~~~~~~~~~~~~~~~~~~~~~~
Level 3: ^^^^^^^^^^^^^^^^^^^^^^
Level 4 (bottom level): ++++++++++++++++++++++
and the one-line title prefixes:
= Document Title (level 0) =
== Section title (level 1) ==
=== Section title (level 2) ===
==== Section title (level 3) ====
===== Section title (level 4) =====
The buildroot manual is currenly using the two-line titles, but this has
multiple disadvantages:
- asciidoc also uses some of the underline symbols for other purposes (like
preformatted code, example blocks, ...), which makes it difficult to do
mass replacements, such as a planned follow-up patch that needs to move
all sections one level down.
- it is difficult to remember which level a given underline symbol (=-~^+)
corresponds to, while counting = signs is easy.
This patch changes all two-level titles to one-level titles in the manual.
The bulk of the change was done with the following Python script, except for
the level 1 titles (-----) as these underlines are also used for literal
code blocks.
This patch only changes the titles, no other changes. In
adding-packages-directory.txt, I did add missing newlines between some
titles and their content.
----------------------------------------------------------------------------
#!/usr/bin/env python
import sys
import mmap
import re
for input in sys.argv[1:]:
f = open(input, 'r+')
f.flush()
s = mmap.mmap(f.fileno(), 0)
# Level 0 (top level): ====================== =
# Level 1: ---------------------- ==
# Level 2: ~~~~~~~~~~~~~~~~~~~~~~ ===
# Level 3: ^^^^^^^^^^^^^^^^^^^^^^ ====
# Level 4 (bottom level): ++++++++++++++++++++++ =====
def replace_title(s, symbol, replacement):
pattern = re.compile(r'(.+\n)\%s{2,}\n' % symbol, re.MULTILINE)
return pattern.sub(r'%s \1' % replacement, s)
new = s
new = replace_title(new, '=', '=')
new = replace_title(new, '+', '=====')
new = replace_title(new, '^', '====')
new = replace_title(new, '~', '===')
#new = replace_title(new, '-', '==')
s.seek(0)
s.write(new)
s.resize(s.tell())
s.close()
f.close()
----------------------------------------------------------------------------
Signed-off-by: Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
Signed-off-by: Peter Korsgaard <peter@korsgaard.com>
2014-05-02 07:47:30 +02:00
|
|
|
=== Patch revision changelog
|
2013-08-09 12:16:46 +02:00
|
|
|
|
|
|
|
|
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
|
2014-03-06 11:07:33 +01:00
|
|
|
letter, an overall changelog may be added to the cover letter in
|
|
|
|
|
addition to the changelog in the individual commits.
|
2014-04-29 21:30:27 +02:00
|
|
|
The best thing to rework a patch series is by interactive rebasing:
|
|
|
|
|
+git rebase -i origin/master+. Consult the git manual for more
|
|
|
|
|
information.
|
2013-08-09 12:16:46 +02:00
|
|
|
|
|
|
|
|
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:
|
|
|
|
|
|
|
|
|
|
---------------
|
2014-03-06 11:07:35 +01:00
|
|
|
Patch title: short explanation, max 72 chars
|
2013-08-09 12:16:46 +02:00
|
|
|
|
2014-03-06 11:07:35 +01:00
|
|
|
A paragraph that explains the problem, and how it manifests itself. If
|
|
|
|
|
the problem is complex, it is OK to add more paragraphs. All paragraphs
|
|
|
|
|
should be wrapped at 72 characters.
|
2013-08-09 12:16:46 +02:00
|
|
|
|
2014-03-06 11:07:35 +01:00
|
|
|
A paragraph that explains the root cause of the problem. Again, more
|
|
|
|
|
than on paragraph is OK.
|
|
|
|
|
|
|
|
|
|
Finally, one or more paragraphs that explain how the problem is solved.
|
|
|
|
|
Don't hesitate to explain complex solutions in detail.
|
|
|
|
|
|
|
|
|
|
Signed-off-by: John DOE <john.doe@example.net>
|
2013-08-09 12:16:46 +02:00
|
|
|
|
|
|
|
|
---
|
|
|
|
|
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" \
|
2014-07-29 17:01:30 +02:00
|
|
|
-M -s -o outgoing origin/master
|
2013-08-09 12:16:46 +02:00
|
|
|
---------------------
|
|
|
|
|
|
2012-11-11 04:14:53 +01:00
|
|
|
[[reporting-bugs]]
|
manual: use one-line titles instead of two-line titles (trivial)
Asciidoc supports two syntaxes for section titles: two-line titles (title
plus underline consisting of a particular symbol), and one-line titles
(title prefixed with a specific number of = signs).
The two-line title underlines are:
Level 0 (top level): ======================
Level 1: ----------------------
Level 2: ~~~~~~~~~~~~~~~~~~~~~~
Level 3: ^^^^^^^^^^^^^^^^^^^^^^
Level 4 (bottom level): ++++++++++++++++++++++
and the one-line title prefixes:
= Document Title (level 0) =
== Section title (level 1) ==
=== Section title (level 2) ===
==== Section title (level 3) ====
===== Section title (level 4) =====
The buildroot manual is currenly using the two-line titles, but this has
multiple disadvantages:
- asciidoc also uses some of the underline symbols for other purposes (like
preformatted code, example blocks, ...), which makes it difficult to do
mass replacements, such as a planned follow-up patch that needs to move
all sections one level down.
- it is difficult to remember which level a given underline symbol (=-~^+)
corresponds to, while counting = signs is easy.
This patch changes all two-level titles to one-level titles in the manual.
The bulk of the change was done with the following Python script, except for
the level 1 titles (-----) as these underlines are also used for literal
code blocks.
This patch only changes the titles, no other changes. In
adding-packages-directory.txt, I did add missing newlines between some
titles and their content.
----------------------------------------------------------------------------
#!/usr/bin/env python
import sys
import mmap
import re
for input in sys.argv[1:]:
f = open(input, 'r+')
f.flush()
s = mmap.mmap(f.fileno(), 0)
# Level 0 (top level): ====================== =
# Level 1: ---------------------- ==
# Level 2: ~~~~~~~~~~~~~~~~~~~~~~ ===
# Level 3: ^^^^^^^^^^^^^^^^^^^^^^ ====
# Level 4 (bottom level): ++++++++++++++++++++++ =====
def replace_title(s, symbol, replacement):
pattern = re.compile(r'(.+\n)\%s{2,}\n' % symbol, re.MULTILINE)
return pattern.sub(r'%s \1' % replacement, s)
new = s
new = replace_title(new, '=', '=')
new = replace_title(new, '+', '=====')
new = replace_title(new, '^', '====')
new = replace_title(new, '~', '===')
#new = replace_title(new, '-', '==')
s.seek(0)
s.write(new)
s.resize(s.tell())
s.close()
f.close()
----------------------------------------------------------------------------
Signed-off-by: Thomas De Schampheleire <thomas.de.schampheleire@gmail.com>
Signed-off-by: Peter Korsgaard <peter@korsgaard.com>
2014-05-02 07:47:30 +02:00
|
|
|
== Reporting issues/bugs or getting help
|
2012-11-11 04:14:53 +01:00
|
|
|
|
2012-11-16 05:54:19 +01:00
|
|
|
Before reporting any issue, please check
|
|
|
|
|
xref:mailing-list-subscribe[the mailing list archive] in case someone has
|
2012-11-11 04:14:53 +01:00
|
|
|
already reported and fixed a similar problem.
|
|
|
|
|
|
2014-03-06 11:07:34 +01:00
|
|
|
However you choose to report bugs or get help, either by
|
|
|
|
|
xref:bugtracker[opening a bug] or by
|
|
|
|
|
xref:mailing-list-subscribe[sending a mail to the mailing list], there are
|
2012-11-16 05:54:19 +01:00
|
|
|
a number of details to provide in order to help people reproduce and
|
2012-11-11 04:14:53 +01:00
|
|
|
find a solution to the issue.
|
|
|
|
|
|
2012-11-16 05:54:19 +01:00
|
|
|
Try to think as if you were trying to help someone else; in
|
2012-11-11 04:14:53 +01:00
|
|
|
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
|
2014-03-06 11:07:34 +01:00
|
|
|
* package(s) for which the build fails
|
2012-11-11 04:14:53 +01:00
|
|
|
* the command that fails and its output
|
|
|
|
|
* any information you think that may be relevant
|
|
|
|
|
|
2014-03-06 11:07:34 +01:00
|
|
|
Additionally, you should add the +.config+ file (or if you know how, a
|
2014-03-28 22:24:46 +01:00
|
|
|
+defconfig+; see xref:customize-store-buildroot-config[]).
|
2012-11-11 04:14:53 +01:00
|
|
|
|
2012-11-16 05:54:19 +01:00
|
|
|
If some of these details are too large, do not hesitate to use a
|
2014-03-06 11:07:34 +01:00
|
|
|
pastebin service. Note that not all available pastebin services will
|
|
|
|
|
preserve Unix-style line terminators when downloading raw pastes.
|
|
|
|
|
Following pastebin services are known to work correctly:
|
|
|
|
|
- https://gist.github.com/
|
|
|
|
|
- http://code.bulix.org/
|
