add experimental protocols and their requirements
Proposal: experimental/ Protocol Development
Problem Statement
wayland-protocols has struggled with development practices for many years. This stagnation typically comes in two flavors:
- barrier to entry
- review hell
By adding a third stage of protocol lifetimes, the "experimental" stage, the barrier
to entry for new protocol development can be lowered, and momentum can be established
in order to carry new protocols through staging/ to stable/ and broad adoption.
tl;dr:
-
experimental/- breaking changes allowed, iterative development -
staging/- no breaking changes allowed, protocols are versioned, fewer changes expected, begin deployment/testing -
stable/- no breaking changes allowed, versioning is still permitted, no changes expected, safe for production use
Experimental Protocols: Inclusion Requirements
This proposal offers a solution for the above problems in the form of a new protocol lifetime stage.
An experimental protocol allows rapid prototyping and hands-on development by promoting that involvement
from the outset. Whereas staging/ protocols must receive some number of ACKs to be merged, an experimental/
protocol requires only that it has no NACKs by the end of its two-week review period. Once this period passes,
the experimental protocol is merged.
NACKs Redefined
At present, the NACK is a heavy-handed response to something deeply wrong with an idea. It is seldom
used and greatly feared. For the purpose of experimental/ protocols, however, it is the perfect tool
for gating inclusion into wayland-protocols as a whole.
Originally, the idea of new protocols needing ACKs came from the people writing all the protocols being the people writing all the compositors. There were far fewer of each, and saying that 50% of implementations needed to agree on an idea for it to ship was very reasonable when 50% was two. Also back then there was the added requirement that all protocols had to be implemented by Weston, the reference implementation.
The community has come a long way from these humble beginnings, but having some form of quality control over what protocols are "blessed" enough to ship with the main repo is still desirable. To that end, even the most slapdash attempt at solving a problem should still be aimed roughly in the right direction, even if the course will eventually be corrected by a large margin.
When a new experimental protocol is submitted, a two week review period will begin. The two week figure is determined based on the goal of achieving more rapid development; if two weeks pass and no members from governance can be bothered to stand up and click the thumbs-down button, then either the governance model is deeply broken or the protocol is alright enough to begin developing in earnest.
A NACK for an experimental protocol carries some variation on the following meanings:
This idea is broken and cannot work.
OR
This approach is fundamentally against the core principles or spirit of Wayland.
A NACK must be well-justified, as determined by members of the governance team, who are assumed to be acting in good faith for the best interests of the project.
WAIT
The alternative to NACK, for experimental protocol proposals, is WAIT. When a member adds a WAIT, two weeks are added to the review period for extended discussion or research. A member may only utilize a single WAIT for a given protocol. If all WAITs are removed, the protocol's review period resets to its original duration, becoming eligible for merge if that period has elapsed.
Experimental Protocols: Development Cycle
The development cycle for an experimental protocol is different from a typical protocol in order to
further promote discussion and engage the community. As a result of beginning at a less stable stage of development
than even staging/ protocols, when potentially zero implementations may exist, the full, public
development cycle may be longer than other protocols, and it may span multiple merge requests. To solve this,
experimental protocols will likely have a single, persistent merge request open from their inception until they
eventually land in stable/. An overview of this may look like:
- create base protocol merge request (
MR 1) ideally include the word DISCUSSION in the title - review period ends
- protocol author creates copy of branch, creates new MR (
MR 2),MR 2is merged - discussion/development continues in
MR 1 - protocol achieves required number of ACKs and implementations for
staging/status - protocol author creates copy of branch, creates new MR (
MR 3),MR 3is merged - discussion/development continues in
MR 1 - protocol achieves required number of ACKs and implementations for
stable/status -
MR 1is merged
Improving Protocol Development: Generating Momentum
A key problem with protocol development is stagnation during the staging/ phase, or just during review
in general. By allowing continuous iteration and development, participating implementations and clients
can test out changes with easier/broader distribution to see what works or does not work in addition to
developing the protocol. Furthermore, by engaging community members in development from the outset,
a protocol can gain enough momentum and persistent interest to avoid languishing in the
indefinite review period that has blocked so many protocols from progressing.
Experimental Protocols: Preventing Inactivity
An experimental protocol should be one that intends to someday become stable/. While there is a lower barrier
to entry for these protocols, this comes with a responsibility for the author to remain active and continue
to develop. To incentivize good behavior here, experimental protocols without author activity for a period
of three months will be notified, given a one week period to respond, and then removed from wayland-protocols.
Activity, in this regard, is defined as one of the following:
- pushing changes to the main MR
- commenting on the main MR
- engaging in discussion on the mailing list persuant to the protocol
IRC discussions are not counted, as it is challenging to keep track of people there.
This requirement is meant to ensure continued involvement and avoid polluting the repository with inactive/dead protocols, not to penalize contributors. As such, authors may elect to give notice on experimental protocols regarding prolonged absences, extending the counter.
Note that protocols removed for inactivity are not considered NACKed, and so they may be re-added at a later time by reopening the base MR and restarting the process.
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.
Experimental Protocols: Potential Issues and Pitfalls, Questions & Answers
This area attempts to explore potential issues that may arise in the course of experimental protocol development.
What if my experimental protocol gets NACKed?
A NACK prevents a protocol from being merged, but it is not final. There is always room for discussion in Open Source. If a protocol proposal receives a NACK, the burden shifts to the author to persuade members that the protocol is worth a second look or to change the protocol/approach to be more palatable.
What if I miss the review period for an experimental protocol and wish I had NACKed?
A merged experimental protocol can still receive NACKs. Experimental protocols are expected to strive
for staging/ status and broader adoption, and a NACK prevents staging/ protocols from being merged.
How does this address contributors attempting to create experimental alternatives to existing in-development protocols?
There is intentionally no explicit addressing of this theoretical problem. If an experimental protocol is proposed which conflicts with an existing in-development protocol, it is up to the community to determine whether the experimental protocol has value, either as a stopgap solution or a superior alternative. If the experimental protocol is deemed undesirable, whether in content or approach, then it should receive a NACK.
How can implementors avoid explosions of version-specific code for experimental protocols?
It is up to the implementor to resolve this issue. Supporting multiple versions of an experimental protocol is always possible, but supporters should only aim to support the latest, and there is no expectation that previous versions will continue to work.
What if my experimental protocol is approaching the 3 month removal period but I am missing ACKs due to reviewer inactivity?
Contributors engaging in good faith protocol development should not be penalized due to reviewer inactivity. It is advised that experimental protocol authors post memes to the base MR until reviewers become active.
What if an experimental protocol author posts memes to the MR for many months rather than furthering development?
It is expected that protocol authors are seriously attempting to reach staging/ status.
If it is determined by members that this is not the case for a given experimental protocol after a three month period
has elapsed, the one week removal notice may be invoked regardless of how good the memes may be.
Is 2 weeks enough time for review? Should it be longer?
Two weeks is chosen as an arbitrary length of time which is longer than a one week vacation but shorter than a month. Artificially extending the review time serves little purpose but to extend the waiting period before collaborative development becomes easier and increase frustrations of developers during that time. An experimental protocol can still receive a subsequent NACK.
Should experimental protocols have some minimal requirement, e.g., one compositor, and one client implementation, posted to their corresponding upstreams?
No. It is sufficient that the members have reviewed (or opted not to review) the protocol. Some implementors may have extremely long review periods, and gating merge on an external review cycle has no bearing on the protocol itself.
Is this supposed to solve all the problems with wayland-protocols?
No. This solves one set of problems. Trying to solve every problem at once leads to no progress. Further work is underway to improve other areas of the project.
ACKs:
- member project name
NACKs:
- member project name