mirror of
https://gitlab.freedesktop.org/wayland/wayland-protocols.git
synced 2026-05-22 20:38:13 +02:00
304 lines
12 KiB
Markdown
304 lines
12 KiB
Markdown
# Wayland protocols
|
|
|
|
wayland-protocols contains Wayland protocols that add functionality not
|
|
available in the Wayland core protocol. Such protocols either add
|
|
completely new functionality, or extend the functionality of some other
|
|
protocol either in Wayland core, or some other protocol in
|
|
wayland-protocols.
|
|
|
|
A protocol in wayland-protocols consists of a directory containing a set
|
|
of XML files containing the protocol specification, and a README file
|
|
containing detailed state and a list of maintainers.
|
|
|
|
wayland-protocols is a standardization body formed of various Wayland
|
|
compositor and client developers. The governance rules are described in
|
|
[GOVERNANCE.md] and the current members are listed in [MEMBERS.md].
|
|
|
|
## Protocol phases
|
|
|
|
Protocols have three currently used phases: the experimental phase, the staging
|
|
phase, and the stable phase. Anything that is merged upstream is in one of
|
|
those phases, with the exception of deprecated protocols and protocols in
|
|
the legacy protocol phases.
|
|
|
|
Backward-incompatible changes can only be introduced in a new major version of
|
|
a protocol. In the experimental phase, a protocol is actively being
|
|
developed and iterated upon, not trying to avoid incompatible changes.
|
|
Protocols in the staging phase should try to minimize backward-incompatible
|
|
changes, and protocols in the stable phase should avoid backward-incompatible
|
|
changes.
|
|
|
|
Anything that is not merged upstream can be iterated and broken freely, but
|
|
care should be taken to ensure that there are no two protocols with the same
|
|
name and version but a different API.
|
|
|
|
During the experimental phase, patches for clients and compositors are written
|
|
as a test vehicle. Such patches should be merged with caution in clients and
|
|
compositors, because the protocol can still change.
|
|
|
|
When a protocol has reached a stage where it is ready for wider adoption,
|
|
it enters the "staging" phase. What this means is that implementation is
|
|
encouraged in clients and compositors where the functionality it specifies is
|
|
wanted.
|
|
|
|
After a staging protocol has been sufficiently tested in the wild and
|
|
proven adequate, its maintainers and the community at large may declare it
|
|
"stable", meaning it is unexpected to become superseded by a new major
|
|
version.
|
|
|
|
## Deprecation
|
|
|
|
A protocol may be deprecated, if it has been replaced by some other
|
|
protocol, or declared undesirable for some other reason. No more changes
|
|
will be made to a deprecated protocol.
|
|
|
|
## Legacy protocol phases
|
|
|
|
An "unstable" protocol refers to a protocol categorization policy
|
|
previously used by wayland-protocols, where certain naming conventions were
|
|
applied, requiring a backward incompatible change to be declared "stable".
|
|
|
|
During this phase, protocol interface names were, in addition to
|
|
the major version postfix, also prefixed with `z` to distinguish them from
|
|
stable protocols.
|
|
|
|
## Protocol directory tree structure
|
|
|
|
Depending on which stage a protocol is in, the protocol is placed within
|
|
the toplevel directory containing the protocols with the same stage.
|
|
Stable protocols are placed in the `stable/` directory, staging protocols
|
|
are placed in the `staging/` directory, experimental protocols are placed
|
|
in the `experimental/` directory, and deprecated protocols are placed in
|
|
the `deprecated/` directory.
|
|
|
|
Unstable protocols (see [Legacy protocol phases]) can be found in the
|
|
`unstable/` directory, but new ones should never be placed here.
|
|
|
|
## Protocol development procedure
|
|
|
|
To propose a new protocol, create a GitLab merge request adding the
|
|
relevant files and `meson.build` entry to the repository with the
|
|
explanation and motivation in the commit message. Protocols are
|
|
organized in namespaces describing their scope ("wp", "xdg" and "ext").
|
|
There are different requirements for each namespace, see [GOVERNANCE
|
|
section 2] for more information.
|
|
|
|
If the new protocol is just an idea, open an issue on the GitLab issue
|
|
tracker. If the protocol isn't ready for complete review yet and is an
|
|
RFC, create a merge request and add the "Draft:" prefix in the title.
|
|
|
|
To propose changes to existing protocols, create a GitLab merge request.
|
|
Please make sure you CC the authors and maintainers of the protocol, who
|
|
are named in the protocol's README.
|
|
|
|
Please include a `Signed-off-by` line at the end of the commit to certify
|
|
that you wrote it or otherwise have the right to pass it on as an
|
|
open-source patch. See the [Developer Certificate of Origin] for a formal
|
|
definition.
|
|
|
|
## Protocol development recommendations
|
|
|
|
It is recommended that protocols be small and specific in scope in order to
|
|
minimize sites of friction.
|
|
|
|
Development discussion should be approached with a fresh, productive mindset
|
|
and an openness to explore contrary ideas.
|
|
|
|
Development discussions must remain civil and technical in nature at all times.
|
|
|
|
## Interface naming convention
|
|
|
|
All protocols should avoid using generic namespaces or no namespaces in
|
|
the protocol interface names in order to minimize risk that the generated
|
|
C API collides with other C API. Interface names that may collide with
|
|
interface names from other protocols should also be avoided.
|
|
|
|
For generic protocols not limited to certain configurations (such as
|
|
specific desktop environment or operating system) the `wp_` prefix
|
|
should be used on all interfaces in the protocol.
|
|
|
|
For protocols allowing clients to configure how their windows are
|
|
managed, the `xdg_` prefix should be used.
|
|
|
|
For operating system specific protocols, the interfaces should be
|
|
prefixed with both `wp_` and the operating system, for example
|
|
`wp_linux_`, or `wp_freebsd_`, etc.
|
|
|
|
For more information about namespaces, see [GOVERNANCE section 2.1].
|
|
|
|
Each new non-experimental protocol XML file must include a major version
|
|
postfix, starting with `-v1`. The purpose of this postfix is to make it
|
|
possible to distinguish between backward incompatible major versions of
|
|
the same protocol.
|
|
|
|
The interfaces in the protocol XML file should as well have the same
|
|
major version postfix in their names.
|
|
|
|
For example, the protocol `foo-bar` may have a XML file
|
|
`foo-bar/foo-bar-v1.xml`, consisting of the interface `wp_foo_bar_v1`,
|
|
corresponding to the major version 1, as well as the newer version
|
|
`foo-bar/foo-bar-v2.xml` consisting of the interface `wp_foo_bar_v2`,
|
|
corresponding to the major version 2.
|
|
|
|
## Use of RFC 2119 keywords
|
|
|
|
Descriptions of all new protocols must use (in lowercase) and adhere to the
|
|
proper meaning of the keywords described in [RFC 2119].
|
|
|
|
All protocol descriptions that follow the guidelines in RFC 2119 must
|
|
incorporate the following text in their toplevel protocol description section:
|
|
|
|
```
|
|
The key words "must", "must not", "required", "shall", "shall not", "should",
|
|
"should not", "recommended", "may", and "optional" in this document are to
|
|
be interpreted as described in IETF RFC 2119.
|
|
```
|
|
|
|
Note that not all existing protocol descriptions conform to RFC 2119. Protocol
|
|
maintainers are encouraged to audit their descriptions, update them as needed
|
|
to follow RFC 2119 guidelines, and mark them as conformant in the way described
|
|
in the previous paragraph.
|
|
|
|
## Backward compatible protocol changes
|
|
|
|
A protocol may receive backward compatible additions and changes. This
|
|
is to be done in the general Wayland way, using `version` and `since` XML
|
|
element attributes.
|
|
|
|
## Backward incompatible protocol changes
|
|
|
|
Protocols shall try to avoid backwards incompatible protocol changes during
|
|
the staging and stable phases.
|
|
|
|
Assuming a backward incompatible change is needed, the procedure for how to
|
|
do so is the following:
|
|
|
|
- Make a copy of the XML file with the major version increased by 1.
|
|
- Increase the major version number in the protocol XML by 1.
|
|
- Increase the major version number in all of the interfaces in the
|
|
XML by 1.
|
|
- Reset the interface version number (interface version attribute) of all
|
|
the interfaces to 1.
|
|
- Remove all of the `since` attributes.
|
|
|
|
## The experimental phase
|
|
|
|
Implementations choosing to support experimental protocols must work to
|
|
support the latest version of the protocol at all times. It is therefore
|
|
recommended that developers only opt-in to supporting protocols they
|
|
have time and resources to actively develop.
|
|
|
|
A runtime option to enable features may also be useful to ensure users
|
|
do not opt-in to potentially broken behavior.
|
|
|
|
There is no expectation or requirement to avoid backwards incompatible changes
|
|
in this phase. It is therefore strongly advised that such consumer projects add
|
|
build-time compile options to enable such protocols in order to avoid compile
|
|
errors from protocol version mismatches.
|
|
|
|
## The staging phase
|
|
|
|
Protocols can enter the wayland-protocols repository in this stage, without
|
|
traversing the experimental phase. The author of an experimental protocol can
|
|
request that it be promoted at any point.
|
|
|
|
In both cases, the protocol must meet the requirements of
|
|
[GOVERNANCE section 2.3] for the staging phase.
|
|
|
|
Protocols in the staging phase must carry the following disclaimer:
|
|
|
|
```
|
|
Warning! The protocol described in this file is currently in the staging
|
|
phase. Backward compatible changes may be added together with the
|
|
corresponding interface version bump. Backward incompatible changes can
|
|
only be done by creating a new major version of the protocol.
|
|
```
|
|
|
|
When a protocol gets promoted from the experimental phase, the namespace prefix
|
|
should be determined, and then the protocol should be renamed and merged into
|
|
the appropriate directory, deleting the `experimental/` entry.
|
|
|
|
## The stable phase
|
|
|
|
Once it has been concluded that a protocol been proven adequate in
|
|
production, and that it is deemed unlikely to receive any backward
|
|
incompatible changes, it may be declared stable.
|
|
|
|
There are other requirements for declaring a protocol stable, see
|
|
[GOVERNANCE section 2.3].
|
|
|
|
Note that the major version of the stable protocol, as well as all the
|
|
interface versions and names, must remain unchanged.
|
|
|
|
The procedure of promoting a protocol to the stable phase is the following:
|
|
|
|
- Create a new directory in the `stable/` toplevel directory with the
|
|
same name as the protocol directory in the `staging/` directory.
|
|
- Copy the final version of the XML that is the version that was
|
|
decided to be declared stable into the new directory. The target name
|
|
should be the same name as the protocol directory plus the version and
|
|
the `.xml` suffix.
|
|
- Remove the disclaimer about the protocol being in the staging phase.
|
|
- Update the `README` file in the staging directory and create a new
|
|
`README` file in the new directory.
|
|
- Replace the disclaimer in the protocol files left in the staging/
|
|
directory with the following:
|
|
|
|
```
|
|
Disclaimer: This protocol has been marked stable. This copy is
|
|
no longer used and only retained for backwards compatibility. The
|
|
canonical version can be found in the stable/ directory.
|
|
```
|
|
|
|
## Releases
|
|
|
|
Each release of wayland-protocols finalizes the version of the protocols
|
|
to their state they had at that time.
|
|
|
|
## Gitlab conventions
|
|
|
|
### Triaging merge requests
|
|
|
|
New merge requests should be triaged. Doing so requires the one doing the
|
|
triage to add a set of initial labels:
|
|
|
|
~"New Protocol" - For a new protocol being added. If it's an amendment to
|
|
an existing protocol, apply the label of the corresponding protocol
|
|
instead. If none exist, create it.
|
|
|
|
~"Needs acks" - If the protocol needs one or more acknowledgements.
|
|
|
|
~"Needs implementations" - If there are not enough implementations of the
|
|
protocol.
|
|
|
|
~"Needs review" - If the protocol is in need of review.
|
|
|
|
~"In 30 day discussion period" - If the protocol needs a 30 day discussion
|
|
period.
|
|
|
|
For the meaning and requirement of acknowledgments and available
|
|
implementations, see the [GOVERNANCE.md] document.
|
|
|
|
### Managing merge requests
|
|
|
|
When merge requests get their needed feedback and items, remove the
|
|
corresponding label that marks it as needing something. For example, if a
|
|
merge request receives all the required acknowledgments, remove the
|
|
~"Needs acks" label, or if 30 days passed since opening, remove any
|
|
~"In 30 day discussion period" label.
|
|
|
|
### Nacking a merge request
|
|
|
|
If the inclusion of a merge request is denied due to one or more Nacks, add
|
|
the ~Nacked label.
|
|
|
|
[GOVERNANCE.md]: GOVERNANCE.md
|
|
[MEMBERS.md]: MEMBERS.md
|
|
[merge request]: https://gitlab.freedesktop.org/wayland/wayland-protocols/merge_requests
|
|
[issue]: https://gitlab.freedesktop.org/wayland/wayland-protocols/issues
|
|
[GOVERNANCE section 2.3]: GOVERNANCE.md#2.3-introducing-new-protocols
|
|
[Legacy protocol phases]: #legacy-protocol-phases
|
|
[GOVERNANCE section 2]: GOVERNANCE.md#2-protocols
|
|
[Developer Certificate of Origin]: https://developercertificate.org/
|
|
[GOVERNANCE section 2.1]: GOVERNANCE.md#21-protocol-namespaces
|
|
[RFC 2119]: https://www.rfc-editor.org/info/rfc2119
|