1 = Contributing to Wayland = 2 3 == Sending patches == 4 5 Patches should be sent to wayland-devel (a] lists.freedesktop.org, using 6 git send-email. See git's documentation for help [1]. 7 8 The first line of a commit message should contain a prefix indicating 9 what part is affected by the patch followed by one sentence that 10 describes the change. For examples: 11 12 protocol: Support scaled outputs and surfaces 13 14 and 15 16 doc: generate server documentation from XML too 17 18 If in doubt what prefix to use, look at other commits that change the 19 same file(s) as the patch being sent. 20 21 The body of the commit message should describe what the patch changes 22 and why, and also note any particular side effects. This shouldn't be 23 empty on most of the cases. It shouldn't take a lot of effort to write 24 a commit message for an obvious change, so an empty commit message 25 body is only acceptable if the questions "What?" and "Why?" are already 26 answered on the one-line summary. 27 28 The lines of the commit message should have at most 76 characters, to 29 cope with the way git log presents them. 30 31 See [2] for a recommended reading on writing commit messages. 32 33 Your patches should also include a Signed-off-by line with your name and 34 email address. If you're not the patch's original author, you should 35 also gather S-o-b's by them (and/or whomever gave the patch to you.) The 36 significance of this is that it certifies that you created the patch, 37 that it was created under an appropriate open source license, or 38 provided to you under those terms. This lets us indicate a chain of 39 responsibility for the copyright status of the code. 40 41 We won't reject patches that lack S-o-b, but it is strongly recommended. 42 43 == Tracking patches and following up == 44 45 Patchwork is used for tracking patches to Wayland and Weston: 46 http://patchwork.freedesktop.org/project/wayland/list/ 47 48 Xwayland patches are tracked with the Xorg project, not here. 49 50 Libinput patches, even though they use the same mailing list as Wayland, are 51 not tracked in the Wayland Patchwork. 52 53 The following applies only to Wayland and Weston. 54 55 If a patch is not found in Patchwork, there is a high possibility for it to be 56 forgotten. Patches attached to bug reports or not arriving to the mailing list 57 because of e.g. subscription issues will not be in Patchwork because Patchwork 58 only collects patches sent to the list. 59 60 When you send a revised version of a patch, it would be very nice to mark your 61 old patch as superseded (or rejected, if that is applicable). You can change 62 the status of your own patches by registering to Patchwork - ownership is 63 identified by email address you use to register. Updating your patch status 64 appropriately will help maintainer work. 65 66 The following patch states are found in Patchwork: 67 68 New 69 Patches under discussion or not yet processed. 70 71 Under review 72 Mostly unused state. 73 74 Accepted 75 The patch is merged in the master branch upstream, as is or slightly 76 modified. 77 78 Rejected 79 The idea or approach is rejected and cannot be fixed by revising 80 the patch. 81 82 RFC 83 Request for comments, not meant to be merged as is. 84 85 Not applicable 86 The email was not actually a patch, or the patch is not for Wayland or 87 Weston. Libinput patches are usually automatically ignored by Wayland 88 Patchwork, but if they get through, they will be marked as Not 89 applicable. 90 91 Changes requested 92 Reviewers determined that changes to the patch are needed. The 93 submitter is expected to send a revised version. (You should 94 not wait for your patch to be set to this state before revising, 95 though.) 96 97 Awaiting upstream 98 Mostly unused as the patch is waiting for upstream actions but 99 is not shown in the default list, which means it is easy to 100 overlook. 101 102 Superseded 103 A revised version of the patch has been submitted. 104 105 Deferred 106 Used mostly during freeze periods before releases, to temporarily 107 hide patches that cannot be merged during a freeze. 108 109 Note, that in the default listing, only patches in New or Under review are 110 shown. 111 112 There is also a command line interface to Patchwork called 'pwclient', see 113 http://patchwork.freedesktop.org/project/wayland/ 114 for links where to get it and the sample .pwclientrc for Wayland/Weston. 115 116 117 == Coding style == 118 119 You should follow the style of the file you're editing. In general, we 120 try to follow the rules below. 121 122 - indent with tabs, and a tab is always 8 characters wide 123 - opening braces are on the same line as the if statement; 124 - no braces in an if-body with just one statement; 125 - if one of the branches of an if-else condition has braces, then the 126 other branch should also have braces; 127 - there is always an empty line between variable declarations and the 128 code; 129 130 static int 131 my_function(void) 132 { 133 int a = 0; 134 135 if (a) 136 b(); 137 else 138 c(); 139 140 if (a) { 141 b(); 142 c(); 143 } else { 144 d(); 145 } 146 } 147 148 - lines should be less than 80 characters wide; 149 - when breaking lines with functions calls, the parameters are aligned 150 with the opening parentheses; 151 - when assigning a variable with the result of a function call, if the 152 line would be longer we break it around the equal '=' sign if it makes 153 sense; 154 155 long_variable_name = 156 function_with_a_really_long_name(parameter1, parameter2, 157 parameter3, parameter4); 158 159 x = function_with_a_really_long_name(parameter1, parameter2, 160 parameter3, parameter4); 161 162 == Licensing == 163 164 Wayland is licensed with the intention to be usable anywhere X.org is. 165 Originally, X.org was covered under the MIT X11 license, but changed to 166 the MIT Expat license. Similarly, Wayland was covered initially as MIT 167 X11 licensed, but changed to the MIT Expat license, following in X.org's 168 footsteps. Other than wording, the two licenses are substantially the 169 same, with the exception of a no-advertising clause in X11 not included 170 in Expat. 171 172 New source code files should specify the MIT Expat license in their 173 boilerplate, as part of the copyright statement. 174 175 == References == 176 177 [1] http://git-scm.com/documentation 178 179 [2] http://who-t.blogspot.de/2009/12/on-commit-messages.html 180 181
