diff options
| author | Simon Ser <contact@emersion.fr> | 2019-11-21 12:25:00 +0100 |
|---|---|---|
| committer | Simon Ser <contact@emersion.fr> | 2019-12-18 17:42:23 +0000 |
| commit | 733de76221223c2ad3ce94a588015e88c4c9dcc7 (patch) | |
| tree | 65e5a39abb256155bf62d01e83d3921537454e18 | |
| parent | f4c76c4cc520efa780ee6ec117dc0a75869ec481 (diff) | |
Convert plaintext documents to Markdown
This converts GOVERNANCE, MEMBERS and README to Markdown documents.
These are only cosmetic changes, the actual contents and wording have
been retained.
GitLab pretty-prints Markdown and adds anchors. We can now add links
from one document to another.
Unfortunately GOVERNANCE lettered lists have been converted to numbered
lists, because Markdown doesn't support the former.
Signed-off-by: Simon Ser <contact@emersion.fr>
Closes: https://gitlab.freedesktop.org/wayland/wayland-protocols/issues/3
| -rw-r--r-- | GOVERNANCE.md (renamed from GOVERNANCE) | 122 | ||||
| -rw-r--r-- | MEMBERS.md (renamed from MEMBERS) | 2 | ||||
| -rw-r--r-- | README.md (renamed from README) | 114 |
3 files changed, 119 insertions, 119 deletions
diff --git a/GOVERNANCE b/GOVERNANCE.md index 912ae5b..76606db 100644 --- a/GOVERNANCE +++ b/GOVERNANCE.md @@ -1,117 +1,117 @@ - wayland-protocols governance +# wayland-protocols governance This document governs the maintenance of wayland-protocols and serves to outline the broader process for standardization of protocol extensions in the Wayland ecosystem. - 1. Membership +## 1. Membership Membership in wayland-protocols is offered to stakeholders in the Wayland ecosystem who have an interest in participating in protocol extension standardization. - 1.1. Membership requirements +### 1.1. Membership requirements -a. Membership is extended to projects, rather than individuals. -b. Members represent general-purpose projects with a stake in multiple Wayland +1. Membership is extended to projects, rather than individuals. +2. Members represent general-purpose projects with a stake in multiple Wayland protocols (e.g. compositors, GUI toolkits, etc), rather than special-purpose applications with a stake in only one or two. -c. Each project must provide one or two named individuals as points-of-contact +3. Each project must provide one or two named individuals as points-of-contact for that project who can be reached to discuss protocol-related matters. -d. During a vote, if two points-of-contact for the same member disagree, the +4. During a vote, if two points-of-contact for the same member disagree, the member's vote is considered blank. - 1.2. Becoming a member +### 1.2. Becoming a member -a. New members who meet the criteria outlined in 1.1 are established by +1. New members who meet the criteria outlined in 1.1 are established by invitation from an existing member. Projects hoping to join should reach out to an existing member asking for this invitation. -b. New members shall write to the wayland-devel mailing list stating their +2. New members shall write to the wayland-devel mailing list stating their intention of joining and their sponsor. -c. The sponsor shall respond acknowledging their sponsorship of the membership. -d. A 14 day discussion period for comments from wayland-protocols members will +3. The sponsor shall respond acknowledging their sponsorship of the membership. +4. A 14 day discussion period for comments from wayland-protocols members will be held. -e. At the conclusion of the discussion period, the new membership is established +5. At the conclusion of the discussion period, the new membership is established unless their application was NACKed by a 1/2 majority of all existing members. - 1.3. Ceasing membership +### 1.3. Ceasing membership -a. A member may step down by writing their intention to do so to the +1. A member may step down by writing their intention to do so to the wayland-devel mailing list. -b. A removal vote may be called for by an existing member by posting to the +2. A removal vote may be called for by an existing member by posting to the wayland-devel mailing list. This begins a 14 day voting & discussion period. -c. At the conclusion of the voting period, the member is removed if the votes +3. At the conclusion of the voting period, the member is removed if the votes total 2/3rds of all current members. -d. Removed members are not eligible to apply for membership again for a period +4. Removed members are not eligible to apply for membership again for a period of 1 year. -e. Following a failed vote, the member who called for the vote cannot +5. Following a failed vote, the member who called for the vote cannot call for a re-vote or propose any other removal for 90 days. - 2. Protocols +## 2. Protocols - 2.1. Protocol namespaces +### 2.1. Protocol namespaces -a. Namespaces are implemented in practice by prefixing each interface name in a +1. Namespaces are implemented in practice by prefixing each interface name in a protocol definition (XML) with the namespace name, and an underscore (e.g. "xdg_wm_base"). -b. Protocols in a namespace may optionally use the namespace followed by a dash +2. Protocols in a namespace may optionally use the namespace followed by a dash in the name (e.g. "xdg-shell"). -c. The "xdg" namespace is established for protocols letting clients +3. The "xdg" namespace is established for protocols letting clients configure its surfaces as "windows", allowing clients to affect how they are managed. -d. The "wp" namespace is established for protocols generally useful to Wayland +4. The "wp" namespace is established for protocols generally useful to Wayland implementations (i.e. "plumbing" protocols). -e. The "ext" namespace is established as a general catch-all for protocols that +5. The "ext" namespace is established as a general catch-all for protocols that fit into no other namespace. - 2.2. Protocol inclusion requirements +### 2.2. Protocol inclusion requirements -a. All protocols found in the "xdg" and "wp" namespaces at the time of writing +1. All protocols found in the "xdg" and "wp" namespaces at the time of writing are grandfathered into their respective namespace without further discussion. -b. Protocols in the "xdg" and "wp" namespace are eligible for inclusion only if +2. Protocols in the "xdg" and "wp" namespace are eligible for inclusion only if ACKed by at least 3 members. -c. Protocols in the "xdg" and "wp" namespace are ineligible for inclusion if +3. Protocols in the "xdg" and "wp" namespace are ineligible for inclusion if if NACKed by any member. -d. Protocols in the "xdg" and "wp" namespaces must have at least 3 open-source +4. Protocols in the "xdg" and "wp" namespaces must have at least 3 open-source implementations (either 1 client + 2 servers, or 2 clients + 1 server) to be eligible for inclusion. -e. Protocols in the "ext" namespace are eligible for inclusion only if ACKed by +5. Protocols in the "ext" namespace are eligible for inclusion only if ACKed by at least one other member. -f. Protocols in the "ext" namespace must have at least one open-source client & +6. Protocols in the "ext" namespace must have at least one open-source client & one open-source server implementation to be eligible for inclusion. -g. "Open-source" is defined as distributed with an Open Source Initiative +7. "Open-source" is defined as distributed with an Open Source Initiative approved license. - 2.3. Introducing new protocols +### 2.3. Introducing new protocols -a. A new protocol may be proposed by submitting a merge request to the +1. A new protocol may be proposed by submitting a merge request to the wayland-protocols Gitlab repository. -b. Protocol proposal posts must include justification for their inclusion in +2. Protocol proposal posts must include justification for their inclusion in their namespace per the requirements outlined in section 2.2. -c. An indefinite discussion period for comments from wayland-protocols members +3. An indefinite discussion period for comments from wayland-protocols members will be held, with a minimum duration of 30 days. Protocols which require a certain level of implementation status, ACKs from members, and so on, should use this time to acquire them. -d. When the proposed protocol meets all requirements for inclusion per section +4. When the proposed protocol meets all requirements for inclusion per section 2.2, and the minimum discussion period has elapsed, the sponsoring member may merge their changes in the wayland-protocol repository. -e. Amendments to existing protocols may be proposed by the same process, with +5. Amendments to existing protocols may be proposed by the same process, with no minimum discussion period. -f. Declaring a protocol stable may be proposed by the same process, with the +6. Declaring a protocol stable may be proposed by the same process, with the regular 30 day minimum discussion period. - 3. Protocol adoption documentation +## 3. Protocol adoption documentation - 3.1. Adoption website +### 3.1. Adoption website -a. This section is informational. -b. A website will be made available for interested parties to browse the +1. This section is informational. +2. A website will be made available for interested parties to browse the implementation status of protocols included in wayland-protocols. -c. A statement from each member of wayland-protocols will be included on the +3. A statement from each member of wayland-protocols will be included on the site. -d. Each protocol will be listed along with its approval status from each member. -e. The approval statuses are: +4. Each protocol will be listed along with its approval status from each member. +5. The approval statuses are: 1. NACK, or "negative acknowledgement", meaning that the member is opposed to the protocol in principle. 2. NOPP, or "no opposition", meaning that the member is not opposed to the @@ -120,30 +120,30 @@ e. The approval statuses are: principle, but does not provide an implementation. 4. IMPL, or "implemented", meaning that the member supports the protocol and provides an implementation. -f. Each member may write a short statement expanding on the rationale for their +6. Each member may write a short statement expanding on the rationale for their approval status, which will be included on the site. -g. A supplementary list of implementations will also be provided on the site, +7. A supplementary list of implementations will also be provided on the site, which may include implementations supported by non-members. - 3.2. Changes to the adoption website +### 3.2. Changes to the adoption website -a. This section is informational. -b. A new protocol is added to the website by the sponsoring member at the - conclusion of the discussion period (section 2.3.c). -c. During the discussion period (section 2.3.c), interested parties may express +1. This section is informational. +2. A new protocol is added to the website by the sponsoring member at the + conclusion of the discussion period (section 2.3.3). +3. During the discussion period (section 2.3.3), interested parties may express their approval status on the Gitlab merge request. The default approval status for members who do not participate in the discussion is "NOPP". -d. Members may change their acknowledgement status or support statement at any - time after the discussion period (section 2.3.c) has closed by simply merging +4. Members may change their acknowledgement status or support statement at any + time after the discussion period (section 2.3.3) has closed by simply merging their update in the wayland-protocols repository. - 4. Amending this document +## 4. Amending this document -a. An amendment to this document may be proposed any member by +1. An amendment to this document may be proposed any member by submitting a merge request on Gitlab. -b. A 30 day discussion period for comments from wayland-protocols members will +2. A 30 day discussion period for comments from wayland-protocols members will be held. -c. At the conclusion of the discussion period, an amendment will become +3. At the conclusion of the discussion period, an amendment will become effective if it's ACKed by at least 2/3rds of all wayland-protocols members, and NACKed by none. The sponsoring member may merge their change to the wayland-protocols repository at this point. @@ -1,4 +1,4 @@ - wayland-protocols members +# wayland-protocols members - EFL/Enlightenment: Mike Blumenkrantz <michael.blumenkrantz@gmail.com> - GTK/Mutter: Jonas Ådahl <jadahl@gmail.com>, @@ -1,5 +1,4 @@ -Wayland protocols ------------------ +# Wayland protocols wayland-protocols contains Wayland protocols that add functionality not available in the Wayland core protocol. Such protocols either add @@ -11,9 +10,9 @@ 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. -Protocol directory tree structure -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Protocols may be 'stable', 'unstable' or 'deprecated', and the interface +## Protocol directory tree structure + +Protocols may be "stable", "unstable" or "deprecated", and the interface and protocol names as well as place in the directory tree will reflect this. @@ -22,8 +21,8 @@ the maintainers. Changes to such protocols will always be backward compatible. An unstable protocol is a protocol currently under development and this -will be reflected in the protocol and interface names. See <<Unstable -naming convention>>. +will be reflected in the protocol and interface names. See [Unstable +naming convention](#unstable-naming-convention). A deprecated protocol is a protocol that has either been replaced by some other protocol, or declared undesirable for some other reason. No more @@ -31,18 +30,18 @@ changes will be made to a deprecated protocol. Depending on which of the above states the protocol is in, the protocol is placed within the toplevel directory containing the protocols with the -same state. Stable protocols are placed in the +stable/+ directory, -unstable protocols are placed in the +unstable/+ directory, and -deprecated protocols are placed in the +deprecated/+ directory. +same state. Stable protocols are placed in the `stable/` directory, +unstable protocols are placed in the `unstable/` directory, and +deprecated protocols are placed in the `deprecated/` directory. + +## Protocol development procedure -Protocol development procedure -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ To propose a new protocol, create a GitLab merge request adding the relevant files and Makefile.am 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. +There are different requirements for each namespace, see [GOVERNANCE +section 2](GOVERNANCE.md#2-protocols) 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 @@ -51,30 +50,31 @@ RFC, create a merge request and add the "WIP:" prefix in the title. To propose changes to existing protocols, create a GitLab merge request. If the changes are backward incompatible changes to an unstable protocol, -see <<Unstable protocol changes>>. +see [Unstable protocol changes](#unstable-protocol-changes). + +## Interface naming convention -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 +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. +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. +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 +](GOVERNANCE.md#21-protocol-namespaces). -For more information about namespaces, see GOVERNANCE section 2.1. +## Unstable naming convention -Unstable naming convention -~~~~~~~~~~~~~~~~~~~~~~~~~~ Unstable protocols have a special naming convention in order to make it possible to make discoverable backward incompatible changes. @@ -90,18 +90,18 @@ There may be more than one minor version per protocol, if there are more than one global. The XML file and protocol name also has the word 'unstable' in them, and -all of the interfaces in the protocol are prefixed with +z+ and +all of the interfaces in the protocol are prefixed with `z` and suffixed with the major version number. -For example, an unstable protocol called foo-bar with major version 2 -containing the two interfaces wp_foo and wp_bar both minor version 1 will -be placed in the directory +unstable/foo-bar/+ consisting of one file -called +README+ and one called +foo-bar-unstable-v2.xml+. The XML file -will consist of two interfaces called +zwp_foo_v2+ and +zwp_bar_v2+ with -the +version+ attribute set to +1+. +For example, an unstable protocol called `foo-bar` with major version 2 +containing the two interfaces `wp_foo` and `wp_bar` both minor version 1 +will be placed in the directory `unstable/foo-bar/` consisting of one file +called `README` and one called `foo-bar-unstable-v2.xml`. The XML file +will consist of two interfaces called `zwp_foo_v2` and `zwp_bar_v2` with +the `version` attribute set to 1. + +## Unstable protocol changes -Unstable protocol changes -~~~~~~~~~~~~~~~~~~~~~~~~~ During the development of a new protocol it is possible that backward incompatible changes are needed. Such a change needs to be represented in the major and minor versions of the protocol. @@ -109,42 +109,42 @@ in the major and minor versions of the protocol. 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 minor version number (interface version attribute) of all - the interfaces to +1+. +- 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 minor version number (interface version attribute) of all + the interfaces to 1. Backward compatible changes within a major unstable version can be done in the regular way as done in core Wayland or in stable protocols. -Declaring a protocol stable -~~~~~~~~~~~~~~~~~~~~~~~~~~~ +## Declaring a protocol stable + Once it is decided that a protocol should be declared stable, meaning no more backward incompatible changes will ever be allowed, one last breakage is needed. The procedure of doing this is the following: - . Create a new directory in the +stable/+ toplevel directory with the - same name as the protocol directory in the +unstable/+ 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 but with the +.xml+ - suffix. - . Rename the name of the protocol in the XML by removing the - 'unstable' part and the major version number. - . Remove the +z+ prefix and the major version number suffix from all - of the interfaces in the protocol. - . Reset all of the interface version attributes to +1+. - . Update the +README+ file in the unstable directory and create a new - +README+ file in the new directory. +- Create a new directory in the `stable/` toplevel directory with the + same name as the protocol directory in the `unstable/` 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 but with the `.xml` + suffix. +- Rename the name of the protocol in the XML by removing the + `unstable` part and the major version number. +- Remove the `z` prefix and the major version number suffix from all + of the interfaces in the protocol. +- Reset all of the interface version attributes to 1. +- Update the `README` file in the unstable directory and create a new + `README` file in the new directory. There are other requirements for declaring a protocol stable, see -GOVERNANCE section 2.3. +[GOVERNANCE section 2.3](GOVERNANCE.md#23-introducing-new-protocols). + +## Releases -Releases -~~~~~~~~ Each release of wayland-protocols finalizes the version of the protocols to their state they had at that time. |