doc/Contributing - external/anongit.freedesktop.org/git/wayland/wayland - Git at Google

 = Contributing to Wayland =

 == Sending patches ==

 Patches should be sent to wayland-devel@lists.freedesktop.org, using
 git send-email. See git's documentation for help [1].

 The first line of a commit message should contain a prefix indicating
 what part is affected by the patch followed by one sentence that
 describes the change. For examples:

     protocol: Support scaled outputs and surfaces

 and

     doc: generate server documentation from XML too

 If in doubt what prefix to use, look at other commits that change the
 same file(s) as the patch being sent.

 The body of the commit message should describe what the patch changes
 and why, and also note any particular side effects. This shouldn't be
 empty on most of the cases. It shouldn't take a lot of effort to write
 a commit message for an obvious change, so an empty commit message
 body is only acceptable if the questions "What?" and "Why?" are already
 answered on the one-line summary.

 The lines of the commit message should have at most 76 characters, to
 cope with the way git log presents them.

 See [2] for a recommended reading on writing commit messages.

 Your patches should also include a Signed-off-by line with your name and
 email address.  If you're not the patch's original author, you should
 also gather S-o-b's by them (and/or whomever gave the patch to you.) The
 significance of this is that it certifies that you created the patch,
 that it was created under an appropriate open source license, or
 provided to you under those terms.  This lets us indicate a chain of
 responsibility for the copyright status of the code.

 We won't reject patches that lack S-o-b, but it is strongly recommended.

 == Tracking patches and following up ==

 Patchwork is used for tracking patches to Wayland and Weston:
 http://patchwork.freedesktop.org/project/wayland/list/

 Xwayland patches are tracked with the Xorg project, not here.

 Libinput patches, even though they use the same mailing list as Wayland, are
 not tracked in the Wayland Patchwork.

 The following applies only to Wayland and Weston.

 If a patch is not found in Patchwork, there is a high possibility for it to be
 forgotten. Patches attached to bug reports or not arriving to the mailing list
 because of e.g. subscription issues will not be in Patchwork because Patchwork
 only collects patches sent to the list.

 When you send a revised version of a patch, it would be very nice to mark your
 old patch as superseded (or rejected, if that is applicable). You can change
 the status of your own patches by registering to Patchwork - ownership is
 identified by email address you use to register. Updating your patch status
 appropriately will help maintainer work.

 The following patch states are found in Patchwork:

   New
 	Patches under discussion or not yet processed.

   Under review
 	Mostly unused state.

   Accepted
 	The patch is merged in the master branch upstream, as is or slightly
 	modified.

   Rejected
 	The idea or approach is rejected and cannot be fixed by revising
 	the patch.

   RFC
 	Request for comments, not meant to be merged as is.

   Not applicable
 	The email was not actually a patch, or the patch is not for Wayland or
 	Weston. Libinput patches are usually automatically ignored by Wayland
 	Patchwork, but if they get through, they will be marked as Not
 	applicable.

   Changes requested
 	Reviewers determined that changes to the patch are needed. The
 	submitter is expected to send a revised version. (You should
 	not wait for your patch to be set to this state before revising,
 	though.)

   Awaiting upstream
 	Mostly unused as the patch is waiting for upstream actions but
 	is not shown in the default list, which means it is easy to
 	overlook.

   Superseded
 	A revised version of the patch has been submitted.

   Deferred
 	Used mostly during freeze periods before releases, to temporarily
 	hide patches that cannot be merged during a freeze.

 Note, that in the default listing, only patches in New or Under review are
 shown.

 There is also a command line interface to Patchwork called 'pwclient', see
 http://patchwork.freedesktop.org/project/wayland/
 for links where to get it and the sample .pwclientrc for Wayland/Weston.


 == Coding style ==

 You should follow the style of the file you're editing. In general, we
 try to follow the rules below.

 - indent with tabs, and a tab is always 8 characters wide
 - opening braces are on the same line as the if statement;
 - no braces in an if-body with just one statement;
 - if one of the branches of an if-else condition has braces, then the
   other branch should also have braces;
 - there is always an empty line between variable declarations and the
   code;

 static int
 my_function(void)
 {
 	int a = 0;

 	if (a)
 		b();
 	else
 		c();

 	if (a) {
 		b();
 		c();
 	} else {
 		d();
 	}
 }

 - lines should be less than 80 characters wide;
 - when breaking lines with functions calls, the parameters are aligned
   with the opening parentheses;
 - when assigning a variable with the result of a function call, if the
   line would be longer we break it around the equal '=' sign if it makes
   sense;

 	long_variable_name =
 		function_with_a_really_long_name(parameter1, parameter2,
 						 parameter3, parameter4);

 	x = function_with_a_really_long_name(parameter1, parameter2,
 					     parameter3, parameter4);


 == Conduct ==

 As a freedesktop.org project, Wayland follows the Contributor Covenant,
 found at:
 https://www.freedesktop.org/wiki/CodeOfConduct

 Please conduct yourself in a respectful and civilised manner when
 interacting with community members on mailing lists, IRC, or bug
 trackers. The community represents the project as a whole, and abusive
 or bullying behaviour is not tolerated by the project.


 == Licensing ==

 Wayland is licensed with the intention to be usable anywhere X.org is.
 Originally, X.org was covered under the MIT X11 license, but changed to
 the MIT Expat license.  Similarly, Wayland was covered initially as MIT
 X11 licensed, but changed to the MIT Expat license, following in X.org's
 footsteps.  Other than wording, the two licenses are substantially the
 same, with the exception of a no-advertising clause in X11 not included
 in Expat.

 New source code files should specify the MIT Expat license in their
 boilerplate, as part of the copyright statement.

 == References ==

 	[1] http://git-scm.com/documentation

 	[2] http://who-t.blogspot.de/2009/12/on-commit-messages.html
	= Contributing to Wayland =

	== Sending patches ==

	Patches should be sent to wayland-devel@lists.freedesktop.org, using
	git send-email. See git's documentation for help [1].

	The first line of a commit message should contain a prefix indicating
	what part is affected by the patch followed by one sentence that
	describes the change. For examples:

	protocol: Support scaled outputs and surfaces

	and

	doc: generate server documentation from XML too

	If in doubt what prefix to use, look at other commits that change the
	same file(s) as the patch being sent.

	The body of the commit message should describe what the patch changes
	and why, and also note any particular side effects. This shouldn't be
	empty on most of the cases. It shouldn't take a lot of effort to write
	a commit message for an obvious change, so an empty commit message
	body is only acceptable if the questions "What?" and "Why?" are already
	answered on the one-line summary.

	The lines of the commit message should have at most 76 characters, to
	cope with the way git log presents them.

	See [2] for a recommended reading on writing commit messages.

	Your patches should also include a Signed-off-by line with your name and
	email address. If you're not the patch's original author, you should
	also gather S-o-b's by them (and/or whomever gave the patch to you.) The
	significance of this is that it certifies that you created the patch,
	that it was created under an appropriate open source license, or
	provided to you under those terms. This lets us indicate a chain of
	responsibility for the copyright status of the code.

	We won't reject patches that lack S-o-b, but it is strongly recommended.

	== Tracking patches and following up ==

	Patchwork is used for tracking patches to Wayland and Weston:
	http://patchwork.freedesktop.org/project/wayland/list/

	Xwayland patches are tracked with the Xorg project, not here.

	Libinput patches, even though they use the same mailing list as Wayland, are
	not tracked in the Wayland Patchwork.

	The following applies only to Wayland and Weston.

	If a patch is not found in Patchwork, there is a high possibility for it to be
	forgotten. Patches attached to bug reports or not arriving to the mailing list
	because of e.g. subscription issues will not be in Patchwork because Patchwork
	only collects patches sent to the list.

	When you send a revised version of a patch, it would be very nice to mark your
	old patch as superseded (or rejected, if that is applicable). You can change
	the status of your own patches by registering to Patchwork - ownership is
	identified by email address you use to register. Updating your patch status
	appropriately will help maintainer work.

	The following patch states are found in Patchwork:

	New
	Patches under discussion or not yet processed.

	Under review
	Mostly unused state.

	Accepted
	The patch is merged in the master branch upstream, as is or slightly
	modified.

	Rejected
	The idea or approach is rejected and cannot be fixed by revising
	the patch.

	RFC
	Request for comments, not meant to be merged as is.

	Not applicable
	The email was not actually a patch, or the patch is not for Wayland or
	Weston. Libinput patches are usually automatically ignored by Wayland
	Patchwork, but if they get through, they will be marked as Not
	applicable.

	Changes requested
	Reviewers determined that changes to the patch are needed. The
	submitter is expected to send a revised version. (You should
	not wait for your patch to be set to this state before revising,
	though.)

	Awaiting upstream
	Mostly unused as the patch is waiting for upstream actions but
	is not shown in the default list, which means it is easy to
	overlook.

	Superseded
	A revised version of the patch has been submitted.

	Deferred
	Used mostly during freeze periods before releases, to temporarily
	hide patches that cannot be merged during a freeze.

	Note, that in the default listing, only patches in New or Under review are
	shown.

	There is also a command line interface to Patchwork called 'pwclient', see
	http://patchwork.freedesktop.org/project/wayland/
	for links where to get it and the sample .pwclientrc for Wayland/Weston.


	== Coding style ==

	You should follow the style of the file you're editing. In general, we
	try to follow the rules below.

	- indent with tabs, and a tab is always 8 characters wide
	- opening braces are on the same line as the if statement;
	- no braces in an if-body with just one statement;
	- if one of the branches of an if-else condition has braces, then the
	other branch should also have braces;
	- there is always an empty line between variable declarations and the
	code;

	static int
	my_function(void)
	{
	int a = 0;

	if (a)
	b();
	else
	c();

	if (a) {
	b();
	c();
	} else {
	d();
	}
	}

	- lines should be less than 80 characters wide;
	- when breaking lines with functions calls, the parameters are aligned
	with the opening parentheses;
	- when assigning a variable with the result of a function call, if the
	line would be longer we break it around the equal '=' sign if it makes
	sense;

	long_variable_name =
	function_with_a_really_long_name(parameter1, parameter2,
	parameter3, parameter4);

	x = function_with_a_really_long_name(parameter1, parameter2,
	parameter3, parameter4);


	== Conduct ==

	As a freedesktop.org project, Wayland follows the Contributor Covenant,
	found at:
	https://www.freedesktop.org/wiki/CodeOfConduct

	Please conduct yourself in a respectful and civilised manner when
	interacting with community members on mailing lists, IRC, or bug
	trackers. The community represents the project as a whole, and abusive
	or bullying behaviour is not tolerated by the project.


	== Licensing ==

	Wayland is licensed with the intention to be usable anywhere X.org is.
	Originally, X.org was covered under the MIT X11 license, but changed to
	the MIT Expat license. Similarly, Wayland was covered initially as MIT
	X11 licensed, but changed to the MIT Expat license, following in X.org's
	footsteps. Other than wording, the two licenses are substantially the
	same, with the exception of a no-advertising clause in X11 not included
	in Expat.

	New source code files should specify the MIT Expat license in their
	boilerplate, as part of the copyright statement.

	== References ==

	[1] http://git-scm.com/documentation

	[2] http://who-t.blogspot.de/2009/12/on-commit-messages.html