CONTRIBUTING.md 12.5 KB
Newer Older
1 2
Contributing to Wayland
=======================
3

4 5
Sending patches
---------------
6

7 8
Patches should be sent to **wayland-devel@lists.freedesktop.org**, using
`git send-email`. See [git documentation] for help.
9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26

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
Eric Engestrom's avatar
Eric Engestrom committed
27
body is only acceptable if the questions "What?" and "Why?" are already
28 29 30 31 32
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.

33 34
See [notes on commit messages] for a recommended reading on writing commit
messages.
35

36 37 38 39 40 41 42 43 44
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.
45

46 47 48 49 50 51 52 53
When you re-send patches, revised or not, it would be very good to document the
changes compared to the previous revision in the commit message and/or the
cover letter. If you have already received Reviewed-by or Acked-by tags, you
should evaluate whether they still apply and include them in the respective
commit messages. Otherwise the tags may be lost, reviewers miss the credit they
deserve, and the patches may cause redundant review effort.


54 55
Tracking patches and following up
---------------------------------
56

57
[Wayland Patchwork](http://patchwork.freedesktop.org/project/wayland/list/) is
58 59 60 61 62 63 64
used for tracking patches to Wayland. Xwayland patches are tracked with the
[Xorg project](https://patchwork.freedesktop.org/project/Xorg/list/)
instead. Weston uses
[GitLab merge requests](https://gitlab.freedesktop.org/wayland/weston/merge_requests)
for code review, and does not use mailing list review at all.

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

67
The following applies only to Wayland.
68 69 70 71 72 73 74 75 76 77 78 79 80 81

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:

82 83
- **New**:
    Patches under discussion or not yet processed.
84

85 86
- **Under review**:
    Mostly unused state.
87

88 89 90
- **Accepted**:
    The patch is merged in the master branch upstream, as is or slightly
    modified.
91

92 93 94
- **Rejected**:
    The idea or approach is rejected and cannot be fixed by revising
    the patch.
95

96 97
- **RFC**:
    Request for comments, not meant to be merged as is.
98

99
- **Not applicable**:
100 101
    The email was not actually a patch, or the patch is not for Wayland.
    Libinput patches are usually automatically ignored by Wayland
102 103
    Patchwork, but if they get through, they will be marked as Not
    applicable.
104

105 106 107 108 109
- **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.)
110

111 112 113 114
- **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.
115

116 117
- **Superseded**:
    A revised version of the patch has been submitted.
118

119 120 121
- **Deferred**:
    Used mostly during freeze periods before releases, to temporarily
    hide patches that cannot be merged during a freeze.
122

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

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


131 132
Coding style
------------
133 134 135 136

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

137 138 139
**Note: this file uses spaces due to markdown rendering issues for tabs.
  Code must be implemented using tabs.**

140 141 142
- 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;
Eric Engestrom's avatar
Eric Engestrom committed
143
- if one of the branches of an if-else condition has braces, then the
144 145 146 147
  other branch should also have braces;
- there is always an empty line between variable declarations and the
  code;

148
```c
149 150 151
static int
my_function(void)
{
152 153 154 155 156 157 158 159 160 161 162 163 164
        int a = 0;

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

        if (a) {
                b();
                c();
        } else {
                d();
        }
165
}
166
```
167 168 169

- lines should be less than 80 characters wide;
- when breaking lines with functions calls, the parameters are aligned
Eric Engestrom's avatar
Eric Engestrom committed
170
  with the opening parentheses;
171 172 173 174
- 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;

175 176 177 178
```c
        long_variable_name =
                function_with_a_really_long_name(parameter1, parameter2,
                                                 parameter3, parameter4);
179

180 181 182
        x = function_with_a_really_long_name(parameter1, parameter2,
                                             parameter3, parameter4);
```
183

184 185
Conduct
=======
186 187 188 189 190 191 192 193 194 195 196

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.


197 198
Licensing
=========
199 200 201 202 203 204

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
Eric Engestrom's avatar
Eric Engestrom committed
205
same, with the exception of a no-advertising clause in X11 not included
206 207 208 209 210
in Expat.

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

211

212 213 214 215 216 217 218 219 220
Review
======

All patches, even trivial ones, require at least one positive review
(Reviewed-by). Additionally, if no Reviewed-by's have been given by
people with commit access, there needs to be at least one Acked-by from
someone with commit access. A person with commit access is expected to be
able to evaluate the patch with respect to the project scope and architecture.

221 222 223 224 225
The below review guidelines are intended to be interpreted in spirit, not by
the letter. There may be circumstances where some guidelines are better
ignored. We rely very much on the judgement of reviewers and commit rights
holders.

226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242
During review, the following matters should be checked:

- The commit message explains why the change is being made.

- The code fits the project's scope.

- The code license is the same MIT licence the project generally uses.

- Stable ABI or API is not broken.

- Stable ABI or API additions must be justified by actual use cases, not only
by speculation. They must also be documented, and it is strongly recommended to
include tests excercising the additions in the test suite.

- The code fits the existing software architecture, e.g. no layering
violations.

243 244 245
- The code is correct and does not introduce new failures for existing users,
does not add new corner-case bugs, and does not introduce new compiler
warnings.
246

247
- The patch does what it says in the commit message and changes nothing else.
248

249 250 251 252 253 254 255 256 257
- The patch is a single logical change. If the commit message addresses
multiple points, it is a hint that the commit might need splitting up.

- A bug fix should target the underlying root cause instead of hiding symptoms.
If a complete fix is not practical, partial fixes are acceptable if they come
with code comments and filed Gitlab issues for the remaining bugs.

- The bug root cause rule applies to external software components as well, e.g.
do not work around kernel driver issues in userspace.
258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274

- The test suite passes.

- The code does not depend on API or ABI which has no working free open source
implementation.

- The code is not dead or untestable. E.g. if there are no free open source
software users for it then it is effectively dead code.

- The code is written to be easy to understand, or if code cannot be clear
enough on its own there are code comments to explain it.

- The code is minimal, i.e. prefer refactor and re-use when possible unless
clarity suffers.

- The code adheres to the style guidelines.

275 276
- In a patch series, every intermediate step adheres to the above guidelines.

277

278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310
Commit rights
=============

Commit rights will be granted to anyone who requests them and fulfills the
below criteria:

- Submitted some (10 as a rule of thumb) non-trivial (not just simple
  spelling fixes and whitespace adjustment) patches that have been merged
  already.

- Are actively participating in public discussions about their work (on the
  mailing list or IRC). This should not be interpreted as a requirement to
  review other peoples patches but just make sure that patch submission isn't
  one-way communication. Cross-review is still highly encouraged.

- Will be regularly contributing further patches. This includes regular
  contributors to other parts of the open source graphics stack who only
  do the occasional development in this project.

- Agrees to use their commit rights in accordance with the documented merge
  criteria, tools, and processes.

To apply for commit rights, create a new issue in gitlab for the respective
project and give it the "accounts" label.

Committers are encouraged to request their commit rights get removed when they
no longer contribute to the project. Commit rights will be reinstated when they
come back to the project.

Maintainers and committers should encourage contributors to request commit
rights, especially junior contributors tend to underestimate their skills.


311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345
Stabilising for releases
========================

A release cycle ends with a stable release which also starts a new cycle and
lifts any code freezes. Gradual code freezing towards a stable release starts
with an alpha release. The release stages of a cycle are:

- **Alpha release**:
    Signified by version number #.#.91.
    Major features must have landed before this. Major features include
    invasive code motion and refactoring, high risk changes, and new stable
    library ABI.

- **Beta release**:
    Signified by version number #.#.92.
    Minor features must have landed before this. Minor features include all
    new features that are not major, low risk changes, clean-ups, and
    documentation. Stable ABI that was new in the alpha release can be removed
    before a beta release if necessary.

- **Release candidates (RC)**:
    Signified by version number #.#.93 and up to #.#.99.
    Bug fixes that are not release critical must have landed before this.
    Release critical bug fixes can still be landed after this, but they may
    call for another RC.

- **Stable release**:
    Signified by version number #.#.0.
    Ideally no changes since the last RC.

Mind that version #.#.90 is never released. It is used during development when
no code freeze is in effect. Stable branches and point releases are not covered
by the above.


346 347
[git documentation]: http://git-scm.com/documentation
[notes on commit messages]: http://who-t.blogspot.de/2009/12/on-commit-messages.html