[PATCH wayland] doc: Add a small contributing guide

[Kristian Høgsberg]

On Tue, Jun 11, 2013 at 06:21:32PM +0300, Ander Conselvan de Oliveira wrote:
> Document what we expect in terms of commit messages and coding style.
> New contributors are usually unaware of this, so it is good to have a
> document to point them too.
> ---
> 
> I probably haven't captured everything here and some might be my opinion
> and not a rule, but I think it would be good to have this and edit/expand
> as needed.
> 
> Cheers,
> Ander

Thanks, that's a good doc to have to point people to.  I committed
with a small change...

> ---
>  doc/Contributing |   83 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
>  doc/Makefile.am  |    2 ++
>  2 files changed, 85 insertions(+)
>  create mode 100644 doc/Contributing
> 
> diff --git a/doc/Contributing b/doc/Contributing
> new file mode 100644
> index 0000000..df94e11
> --- /dev/null
> +++ b/doc/Contributing
> @@ -0,0 +1,83 @@
> += Contributing to Wayland =
> +
> +== Sending patches ==
> +
> +Patches should be sent to wayland-devel at 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.

... I removed the period at the end here - we don't use punctuation in
commit headers, think of it as a newspaper headline.

> +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 recommend reading on writing commit messages.
> +
> +== 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 codition has braces, than 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 parenthesis;
> +- 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);
> +
> +== References ==
> +
> +	[1] http://git-scm.com/documentation
> +
> +	[2] http://who-t.blogspot.de/2009/12/on-commit-messages.html
> +
> diff --git a/doc/Makefile.am b/doc/Makefile.am
> index 1efd3e2..14637af 100644
> --- a/doc/Makefile.am
> +++ b/doc/Makefile.am
> @@ -1 +1,3 @@
>  SUBDIRS = doxygen publican man
> +
> +EXTRA_DIST = Contributing
> -- 
> 1.7.10.4
> 
> _______________________________________________
> wayland-devel mailing list
> wayland-devel at lists.freedesktop.org
> http://lists.freedesktop.org/mailman/listinfo/wayland-devel