docs/manual/contribute.txt - buildroot - Git at Google

 // -*- 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[]).
	// -- 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[]).