diff --git a/GOVERNANCE.md b/GOVERNANCE.md index e6e203faed0cf4133d230daf4833e88a0e79dfae..9da404d7f60716453f57414f55cbcc7bf5190dc0 100644 --- a/GOVERNANCE.md +++ b/GOVERNANCE.md @@ -74,6 +74,12 @@ standardization. 5. The "ext" namespace is established as a general catch-all for protocols that fit into no other namespace. +#### 2.1.1 Experimental protocol namespacing + +1. Experimental protocols begin with the "xx" namespace and do not include any relation + to namespaces specified in section 2.1. +2. Namespacing of experimental protocols is determined upon promotion. + ### 2.2. Protocol inclusion requirements 1. All protocols found in the "xdg" and "wp" namespaces at the time of writing @@ -95,6 +101,13 @@ standardization. by at least one member project. For the purposes of this clause, reviews from the individual protocol author(s) are disregarded. +#### 2.2.1 Experimental protocol inclusion requirements + +1. Experimental protocols must be valid XML which can be consumed by wayland-scanner. +2. All such protocols must be created with a proposal merge request outlining the + need for and purpose of the protocol. +3. All such protocols must be clearly tagged as experimental. + ### 2.3. Introducing new protocols 1. A new protocol may be proposed by submitting a merge request to the @@ -113,6 +126,32 @@ standardization. 6. Declaring a protocol stable may be proposed by the same process, with the regular 30 day minimum discussion period. +### 2.3.1 Introducing new experimental protocols + +1. Experimental protocols are merged into wayland-protocols after a two + week review period upon the author's request unless a NACK has been given or + a WAIT is in progress. +2. If all NACKs are removed from an experimental protocol, the two week review period is + started anew. + +### 2.3.2 Experimental protocol removal policy + +1. Unmaintained experimental protocols are removed after a three month period of + inactivity by its author, as determined by all of the following being true: + * No changes have been made to the protocol by the author + * No comments have been made to the protocol merge request by the author + * No mails have been sent to the mailing list persuant to the protocol by the author +2. A notification of intent to remove shall be given to the author in the protocol + merge request, and the protocol shall only be removed following a one week grace period + of continued inactivity. + +### 2.3.3 Experimental protocol promotion + +1. A merged experimental protocol may be promoted to `staging/` + upon request if it meets the requirements for landing as a + `staging/` protocol. +2. Upon promotion, an experimental protocol is removed from `experimental/`. + ## 3. Amending this document 1. An amendment to this document may be proposed by any member project by diff --git a/README.md b/README.md index 901047c60977c80f2483acf190c1cfc098574bda..7316df6bc35d6c4a23da1b6f23fe0bb01e6c490c 100644 --- a/README.md +++ b/README.md @@ -19,13 +19,14 @@ compositor and client developers. The governance rules are described in Protocols in general have three phases: the development phase, the testing phase, and the stable phase. -In the development phase, a protocol is not officially part of -wayland-protocols, but is actively being developed, for example by +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. During this phase, patches for clients and compositors are written as a test -vehicle. Such patches must not be merged in clients and compositors, because -the protocol can still change. +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 @@ -114,10 +115,10 @@ prefixed with both `wp_` and the operating system, for example For more information about namespaces, see [GOVERNANCE section 2.1]. -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. +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. @@ -164,7 +165,22 @@ 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 +## Backward incompatible protocol changes for experimental protocols + +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 @@ -181,6 +197,29 @@ do so is the following: the interfaces to 1. - Remove all of the `since` attributes. +## Experimental Protocols: Development Recommendations + +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 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. + +## Promoting a protocol from experimental + +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. + ## Declaring a protocol stable Once it has been concluded that a protocol been proven adequate in