2018-06-13 18:21:43 +08:00
|
|
|
Contributing to Wayland
|
|
|
|
=======================
|
2013-06-11 23:21:32 +08:00
|
|
|
|
2018-06-13 18:21:43 +08:00
|
|
|
Sending patches
|
|
|
|
---------------
|
2013-06-11 23:21:32 +08:00
|
|
|
|
2018-06-13 18:21:43 +08:00
|
|
|
Patches should be sent to **wayland-devel@lists.freedesktop.org**, using
|
|
|
|
`git send-email`. See [git documentation] for help.
|
2013-06-11 23:21:32 +08:00
|
|
|
|
|
|
|
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
|
2016-05-02 16:49:36 +08:00
|
|
|
body is only acceptable if the questions "What?" and "Why?" are already
|
2013-06-11 23:21:32 +08:00
|
|
|
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.
|
|
|
|
|
2018-06-13 18:21:43 +08:00
|
|
|
See [notes on commit messages] for a recommended reading on writing commit
|
|
|
|
messages.
|
2013-06-11 23:21:32 +08:00
|
|
|
|
2016-03-05 02:50:23 +08:00
|
|
|
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.
|
2015-09-22 14:56:24 +08:00
|
|
|
|
2018-07-03 18:32:02 +08:00
|
|
|
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.
|
|
|
|
|
|
|
|
|
2018-06-13 18:21:43 +08:00
|
|
|
Tracking patches and following up
|
|
|
|
---------------------------------
|
2015-09-22 14:56:24 +08:00
|
|
|
|
2018-06-13 18:21:43 +08:00
|
|
|
[Wayland Patchwork](http://patchwork.freedesktop.org/project/wayland/list/) is
|
|
|
|
used for tracking patches to Wayland and Weston. Xwayland patches are tracked
|
|
|
|
with the [Xorg project](https://patchwork.freedesktop.org/project/Xorg/list/)
|
|
|
|
instead. Libinput patches, even though they use the same mailing list as
|
|
|
|
Wayland, are not tracked in the Wayland Patchwork.
|
2015-09-22 14:56:24 +08:00
|
|
|
|
|
|
|
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:
|
|
|
|
|
2018-06-13 18:21:43 +08:00
|
|
|
- **New**:
|
|
|
|
Patches under discussion or not yet processed.
|
2015-09-22 14:56:24 +08:00
|
|
|
|
2018-06-13 18:21:43 +08:00
|
|
|
- **Under review**:
|
|
|
|
Mostly unused state.
|
2015-09-22 14:56:24 +08:00
|
|
|
|
2018-06-13 18:21:43 +08:00
|
|
|
- **Accepted**:
|
|
|
|
The patch is merged in the master branch upstream, as is or slightly
|
|
|
|
modified.
|
2015-09-22 14:56:24 +08:00
|
|
|
|
2018-06-13 18:21:43 +08:00
|
|
|
- **Rejected**:
|
|
|
|
The idea or approach is rejected and cannot be fixed by revising
|
|
|
|
the patch.
|
2015-09-22 14:56:24 +08:00
|
|
|
|
2018-06-13 18:21:43 +08:00
|
|
|
- **RFC**:
|
|
|
|
Request for comments, not meant to be merged as is.
|
2015-09-22 14:56:24 +08:00
|
|
|
|
2018-06-13 18:21:43 +08:00
|
|
|
- **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.
|
2015-09-22 14:56:24 +08:00
|
|
|
|
2018-06-13 18:21:43 +08:00
|
|
|
- **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.)
|
2015-09-22 14:56:24 +08:00
|
|
|
|
2018-06-13 18:21:43 +08:00
|
|
|
- **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.
|
2015-09-22 14:56:24 +08:00
|
|
|
|
2018-06-13 18:21:43 +08:00
|
|
|
- **Superseded**:
|
|
|
|
A revised version of the patch has been submitted.
|
2015-09-22 14:56:24 +08:00
|
|
|
|
2018-06-13 18:21:43 +08:00
|
|
|
- **Deferred**:
|
|
|
|
Used mostly during freeze periods before releases, to temporarily
|
|
|
|
hide patches that cannot be merged during a freeze.
|
2015-09-22 14:56:24 +08:00
|
|
|
|
2018-06-13 18:21:43 +08:00
|
|
|
Note, that in the default listing, only patches in *New* or *Under review* are
|
2015-09-22 14:56:24 +08:00
|
|
|
shown.
|
|
|
|
|
2018-06-13 18:21:43 +08:00
|
|
|
There is also a command line interface to Patchwork called `pwclient`, see
|
2015-09-22 14:56:24 +08:00
|
|
|
http://patchwork.freedesktop.org/project/wayland/
|
2018-06-13 18:21:43 +08:00
|
|
|
for links where to get it and the sample `.pwclientrc` for Wayland/Weston.
|
2015-09-22 14:56:24 +08:00
|
|
|
|
|
|
|
|
2018-06-13 18:21:43 +08:00
|
|
|
Coding style
|
|
|
|
------------
|
2013-06-11 23:21:32 +08:00
|
|
|
|
|
|
|
You should follow the style of the file you're editing. In general, we
|
|
|
|
try to follow the rules below.
|
|
|
|
|
2018-06-13 18:21:43 +08:00
|
|
|
**Note: this file uses spaces due to markdown rendering issues for tabs.
|
|
|
|
Code must be implemented using tabs.**
|
|
|
|
|
2013-06-11 23:21:32 +08:00
|
|
|
- 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;
|
2016-05-02 16:49:36 +08:00
|
|
|
- if one of the branches of an if-else condition has braces, then the
|
2013-06-11 23:21:32 +08:00
|
|
|
other branch should also have braces;
|
|
|
|
- there is always an empty line between variable declarations and the
|
|
|
|
code;
|
|
|
|
|
2018-06-13 18:21:43 +08:00
|
|
|
```c
|
2013-06-11 23:21:32 +08:00
|
|
|
static int
|
|
|
|
my_function(void)
|
|
|
|
{
|
2018-06-13 18:21:43 +08:00
|
|
|
int a = 0;
|
|
|
|
|
|
|
|
if (a)
|
|
|
|
b();
|
|
|
|
else
|
|
|
|
c();
|
|
|
|
|
|
|
|
if (a) {
|
|
|
|
b();
|
|
|
|
c();
|
|
|
|
} else {
|
|
|
|
d();
|
|
|
|
}
|
2013-06-11 23:21:32 +08:00
|
|
|
}
|
2018-06-13 18:21:43 +08:00
|
|
|
```
|
2013-06-11 23:21:32 +08:00
|
|
|
|
|
|
|
- lines should be less than 80 characters wide;
|
|
|
|
- when breaking lines with functions calls, the parameters are aligned
|
2016-05-02 16:49:36 +08:00
|
|
|
with the opening parentheses;
|
2013-06-11 23:21:32 +08:00
|
|
|
- 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;
|
|
|
|
|
2018-06-13 18:21:43 +08:00
|
|
|
```c
|
|
|
|
long_variable_name =
|
|
|
|
function_with_a_really_long_name(parameter1, parameter2,
|
|
|
|
parameter3, parameter4);
|
2013-06-11 23:21:32 +08:00
|
|
|
|
2018-06-13 18:21:43 +08:00
|
|
|
x = function_with_a_really_long_name(parameter1, parameter2,
|
|
|
|
parameter3, parameter4);
|
|
|
|
```
|
2013-06-11 23:21:32 +08:00
|
|
|
|
2018-06-13 18:21:43 +08:00
|
|
|
Conduct
|
|
|
|
=======
|
2017-04-06 22:09:37 +08:00
|
|
|
|
|
|
|
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.
|
|
|
|
|
|
|
|
|
2018-06-13 18:21:43 +08:00
|
|
|
Licensing
|
|
|
|
=========
|
2015-06-11 02:48:53 +08:00
|
|
|
|
|
|
|
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
|
2016-05-02 16:49:36 +08:00
|
|
|
same, with the exception of a no-advertising clause in X11 not included
|
2015-06-11 02:48:53 +08:00
|
|
|
in Expat.
|
|
|
|
|
|
|
|
New source code files should specify the MIT Expat license in their
|
|
|
|
boilerplate, as part of the copyright statement.
|
|
|
|
|
2013-06-11 23:21:32 +08:00
|
|
|
|
2018-06-13 21:02:51 +08:00
|
|
|
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.
|
|
|
|
|
2018-07-03 18:32:00 +08:00
|
|
|
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.
|
|
|
|
|
2018-06-13 21:02:51 +08:00
|
|
|
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.
|
|
|
|
|
2018-07-03 18:32:01 +08:00
|
|
|
- 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.
|
2018-06-13 21:02:51 +08:00
|
|
|
|
2018-07-03 18:32:01 +08:00
|
|
|
- The patch does what it says in the commit message and changes nothing else.
|
2018-06-13 21:02:51 +08:00
|
|
|
|
2018-07-03 18:32:01 +08:00
|
|
|
- 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.
|
2018-06-13 21:02:51 +08:00
|
|
|
|
|
|
|
- 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.
|
|
|
|
|
2018-07-03 18:32:01 +08:00
|
|
|
- In a patch series, every intermediate step adheres to the above guidelines.
|
|
|
|
|
2018-06-13 21:02:51 +08:00
|
|
|
|
2018-06-15 22:25:07 +08:00
|
|
|
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.
|
|
|
|
|
|
|
|
|
2018-06-13 18:21:43 +08:00
|
|
|
[git documentation]: http://git-scm.com/documentation
|
|
|
|
[notes on commit messages]: http://who-t.blogspot.de/2009/12/on-commit-messages.html
|