mirror of
https://gitlab.freedesktop.org/wayland/wayland-protocols.git
synced 2025-12-28 08:40:10 +01:00
Merge branch 'wip/protocol-phases-experimental' into 'main'
README: Suggested a new development model for experimental protocols See merge request wayland/wayland-protocols!394
This commit is contained in:
Sebastian Wick
commit
234ebc2746
1 changed files with 89 additions and 80 deletions
169
README.md
169
README.md
|
|
@ -16,29 +16,24 @@ compositor and client developers. The governance rules are described in
|
|||
|
||||
## Protocol phases
|
||||
|
||||
Protocols in general have three phases: the development phase, the testing
|
||||
Protocols in general have three phases: the experimental phase, the staging
|
||||
phase, and the stable phase.
|
||||
|
||||
In the development phase, a protocol may be added to wayland-protocols
|
||||
as `experimental/`. It is actively being developed, for example by
|
||||
iterating over it in a [merge request] or planning it in an [issue].
|
||||
Extensions in this phase can have backward incompatible changes.
|
||||
Major versions of protocols in all phases, cannot have backward incompatible
|
||||
changes. However, they may be completely replaced with a new major version, or a
|
||||
different protocol altogether, if design flaws are found.
|
||||
|
||||
In the experimental phase, a protocol is actively being developed, for example
|
||||
by iterating over it in a [merge request] or planning it in an [issue].
|
||||
|
||||
During this 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,
|
||||
and after the [GOVERNANCE section 2.3] requirements have been met, it enters
|
||||
the "testing" phase. At this point, the protocol is added to the `staging/`
|
||||
directory of wayland-protocols and made part of a release. What this means is
|
||||
that implementation is encouraged in clients and compositors where the
|
||||
functionality it specifies is wanted.
|
||||
|
||||
Extensions in staging cannot have backward incompatible changes, in that
|
||||
sense they are equal to stable extensions. However, they may be completely
|
||||
replaced with a new major version, or a different protocol extension altogether,
|
||||
if design flaws are found in the testing phase.
|
||||
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
|
||||
|
|
@ -54,11 +49,10 @@ 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 protocols initially
|
||||
placed in the `unstable/` directory had certain naming conventions were
|
||||
previously used by wayland-protocols, where certain naming conventions were
|
||||
applied, requiring a backward incompatible change to be declared "stable".
|
||||
|
||||
During this phase, protocol extension interface names were, in addition to
|
||||
During this phase, protocol interface names were, in addition to
|
||||
the major version postfix, also prefixed with `z` to distinguish them from
|
||||
stable protocols.
|
||||
|
||||
|
|
@ -67,8 +61,9 @@ stable protocols.
|
|||
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, and deprecated protocols are
|
||||
placed in the `deprecated/` directory.
|
||||
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.
|
||||
|
|
@ -125,30 +120,24 @@ prefixed with both `wp_` and the operating system, for example
|
|||
|
||||
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.
|
||||
Each new 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 only exception to this rule are devel protocols which must include
|
||||
the postfix `-devel` instead.
|
||||
|
||||
The interfaces in the protocol XML file should as well have the same
|
||||
major version postfix in their names.
|
||||
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.
|
||||
|
||||
## Include a disclaimer
|
||||
|
||||
Include the following disclaimer:
|
||||
|
||||
```
|
||||
Warning! The protocol described in this file is currently in the testing
|
||||
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 extension.
|
||||
```
|
||||
The devel protocol `foo-baz` may have a XML file
|
||||
`foo-baz/foo-baz-devel.xml`, consisting of the interface `foo_baz_devel`.
|
||||
|
||||
## Use of RFC 2119 keywords
|
||||
|
||||
|
|
@ -175,26 +164,10 @@ 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 for experimental protocols
|
||||
## Backward incompatible protocol changes
|
||||
|
||||
A protocol in the experimental phase should expect to see backward incompatible
|
||||
changes at any time.
|
||||
|
||||
Assuming a backward incompatible change is needed here, the procedure for how to
|
||||
do so is the following:
|
||||
|
||||
- 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.
|
||||
|
||||
## Backward incompatible protocol changes for testing protocols
|
||||
|
||||
While not preferred, a protocol may at any stage, especially during the
|
||||
testing phase, when it is located in the `staging/` directory, see
|
||||
backward incompatible 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:
|
||||
|
|
@ -207,36 +180,78 @@ do so is the following:
|
|||
the interfaces to 1.
|
||||
- Remove all of the `since` attributes.
|
||||
|
||||
## Experimental Protocols: Development Recommendations
|
||||
## 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.
|
||||
Protocols in the experimental phase are recommended to use an experimental
|
||||
devel protocol file and make all changes, compatible or incompatible, in that
|
||||
file. They do not have a major version and instead use the postfix `devel`.
|
||||
The interface versions shall always stay at zero. Devel protocols are not meant
|
||||
to be implemented directly.
|
||||
|
||||
A protocol snapshot which is meant to be implemented by developers can be
|
||||
created when the need arises. A snapshot of the XML file in its current state
|
||||
shall be used to create the next major protocol version with the following
|
||||
procedure:
|
||||
|
||||
- Make a copy of the XML file and replace the `-devel` postfix with the next
|
||||
free major version.
|
||||
- Replace the `_devel` postfix in the protocol XML with the next free major
|
||||
version.
|
||||
- Replace the `_devel` postfix in all of the interfaces in the XML with the next
|
||||
free major version.
|
||||
|
||||
Implementations choosing to support experimental protocols must work to support
|
||||
the latest major 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 for stability between experimental
|
||||
protocol versions. 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.
|
||||
Protocols in the experimental phase must carry the following disclaimer:
|
||||
|
||||
## Promoting a protocol from experimental
|
||||
```
|
||||
Warning! The protocol described in this file is currently in the
|
||||
experimental phase. Backwards incompatible major versions of the
|
||||
protocol are to be expected. Exposing this protocol without an opt-in
|
||||
mechanism is discouraged.
|
||||
```
|
||||
|
||||
The author of an experimental protocol can request that it be promoted at any point
|
||||
when it meets the requirements for `staging/`. At such time,
|
||||
the namespace prefix should be determined, and then the protocol should be
|
||||
renamed and merged into the appropriate directory, deleting the `experimental/`
|
||||
entry.
|
||||
## The staging phase
|
||||
|
||||
## Declaring a protocol stable
|
||||
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.
|
||||
|
||||
The procedure of doing this is the following:
|
||||
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.
|
||||
|
|
@ -244,24 +259,18 @@ The procedure of doing this is the following:
|
|||
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 testing phase.
|
||||
- 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 extension has been marked stable. This copy is
|
||||
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.
|
||||
```
|
||||
|
||||
Note that the major version of the stable protocol extension, as well as
|
||||
all the interface versions and names, must remain unchanged.
|
||||
|
||||
There are other requirements for declaring a protocol stable, see
|
||||
[GOVERNANCE section 2.3].
|
||||
|
||||
## Releases
|
||||
|
||||
Each release of wayland-protocols finalizes the version of the protocols
|
||||
|
|
|
|||
Loading…
Add table
Reference in a new issue