1 files changed, 150 insertions, 0 deletions
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..16df4dc
--- /dev/null
+++ b/README.md
@@ -0,0 +1,150 @@
+# 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.
+
+## 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.
+
+A stable protocol is a protocol which has been declared stable by
+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](#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
+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.
+
+## 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](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
+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](#unstable-protocol-changes).
+
+## 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
+](GOVERNANCE.md#21-protocol-namespaces).
+
+## Unstable naming convention
+
+Unstable protocols have a special naming convention in order to make it
+possible to make discoverable backward incompatible changes.
+
+An unstable protocol has at least two versions: the major version, which
+represents backward incompatible changes, and the minor version, which
+represents backward compatible changes to the interfaces in the protocol.
+
+The major version is part of the XML file name, the protocol name in the
+XML, and interface names in the protocol.
+
+Minor versions are the version attributes of the interfaces in the XML.
+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
+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.
+
+## 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.
+
+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.
+
+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
+
+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.
+
+There are other requirements for declaring a protocol stable, see
+[GOVERNANCE section 2.3](GOVERNANCE.md#23-introducing-new-protocols).
+
+## Releases
+
+Each release of wayland-protocols finalizes the version of the protocols
+to their state they had at that time.