6.88 KB
Newer Older
1 2
Contributing to Wayland

4 5
Sending patches

7 8
Patches should be sent to ****, 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


    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
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

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.

46 47
Tracking patches and following up

49 50 51 52 53
[Wayland Patchwork]( is
used for tracking patches to Wayland and Weston. Xwayland patches are tracked
with the [Xorg project](
instead. Libinput patches, even though they use the same mailing list as
Wayland, are not tracked in the Wayland Patchwork.
54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69

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:

70 71
- **New**:
    Patches under discussion or not yet processed.

73 74
- **Under review**:
    Mostly unused state.

76 77 78
- **Accepted**:
    The patch is merged in the master branch upstream, as is or slightly

80 81 82
- **Rejected**:
    The idea or approach is rejected and cannot be fixed by revising
    the patch.

84 85
- **RFC**:
    Request for comments, not meant to be merged as is.

87 88 89 90 91
- **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

93 94 95 96 97
- **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,

99 100 101 102
- **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

104 105
- **Superseded**:
    A revised version of the patch has been submitted.

107 108 109
- **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
112 113

There is also a command line interface to Patchwork called `pwclient`, see
for links where to get it and the sample `.pwclientrc` for Wayland/Weston.
117 118

119 120
Coding style
121 122 123 124

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

125 126 127
**Note: this file uses spaces due to markdown rendering issues for tabs.
  Code must be implemented using tabs.**

128 129 130
- 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
- if one of the branches of an if-else condition has braces, then the
132 133 134 135
  other branch should also have braces;
- there is always an empty line between variable declarations and the

137 138 139
static int
140 141 142 143 144 145 146 147 148 149 150 151 152
        int a = 0;

        if (a)

        if (a) {
        } else {
155 156 157

- 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
  with the opening parentheses;
159 160 161 162
- 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

163 164 165 166
        long_variable_name =
                function_with_a_really_long_name(parameter1, parameter2,
                                                 parameter3, parameter4);

168 169 170
        x = function_with_a_really_long_name(parameter1, parameter2,
                                             parameter3, parameter4);

172 173
174 175 176 177 178 179 180 181 182 183 184

As a project, Wayland follows the Contributor Covenant,
found at:

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.

185 186
187 188 189 190 191 192

Wayland is licensed with the intention to be usable anywhere is.
Originally, 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's
footsteps.  Other than wording, the two licenses are substantially the
Eric Engestrom's avatar
Eric Engestrom committed
same, with the exception of a no-advertising clause in X11 not included
194 195 196 197 198
in Expat.

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


200 201
[git documentation]:
[notes on commit messages]: