From d95cf312019bed4768a2e97ec73dc926eddc4dbe Mon Sep 17 00:00:00 2001 From: Pekka Paalanen Date: Wed, 13 Jun 2018 12:45:36 +0300 Subject: doc: move Contributing Gitlab expects a CONTRIBUTING.md in the root directory, so move our guide there. Conversion to proper markup is a follow-up patch. Signed-off-by: Pekka Paalanen Reviewed-by: Peter Hutterer Reviewed-by: Daniel Stone --- CONTRIBUTING.md | 193 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ Makefile.am | 2 +- doc/Contributing | 193 ------------------------------------------------------- doc/Makefile.am | 2 - 4 files changed, 194 insertions(+), 196 deletions(-) create mode 100644 CONTRIBUTING.md delete mode 100644 doc/Contributing diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..9475271 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,193 @@ += 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 + diff --git a/Makefile.am b/Makefile.am index 741db5e..697c517 100644 --- a/Makefile.am +++ b/Makefile.am @@ -121,7 +121,7 @@ BUILT_SOURCES = \ CLEANFILES = $(BUILT_SOURCES) doc/doxygen/doxygen_sqlite3.db DISTCLEANFILES = src/wayland-version.h -EXTRA_DIST = +EXTRA_DIST = CONTRIBUTING.md diff --git a/doc/Contributing b/doc/Contributing deleted file mode 100644 index 9475271..0000000 --- a/doc/Contributing +++ /dev/null @@ -1,193 +0,0 @@ -= 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 - diff --git a/doc/Makefile.am b/doc/Makefile.am index 14637af..1efd3e2 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -1,3 +1 @@ SUBDIRS = doxygen publican man - -EXTRA_DIST = Contributing -- cgit v1.2.3-70-g09d2