| = 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); |
| |
| == 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 |
| |