Break specification into levels

[reillyeon]

Chrome has been running an Origin Trial for the "screen" wake lock type since Chrome 79 with positive feedback from developers. The feedback on mozilla/standards-positions#210 on this subset of the specification is also trending in a positive direction.

In order to reduce this specification to the subset that Chrome intends to ship soon and Mozilla appears potentially supportive of I propose that the "system" wake lock feature be removed from the main specification document. This will become "Wake Lock API Level 1". Work on other types of wake locks, including a "system" or "cpu" wake lock as explored in #232 can continue to be drafted and discussed as "Wake Lock API Level 2".

In "Wake Lock API Level 1" the currently proposed IDL interface will remain the same except the type parameter will be removed from the request() method. This enum will move to "Wake Lock API Level 2", where the request() method will take a single parameter with a default value of "screen". This will reserve the parameter for use by future extensions to the API as they are developed in a way that retains compatibility with code written against Level 1.

@kenchris @marcoscaceres, what do you think of this proposal?

[hadriann]

In order to reduce this specification to the subset that Chrome intends to ship soon [...] I propose that the "system" wake lock feature be removed from the main specification

If I understand correctly, that would mean to tailor a specification based on an implementation - while usually things are the other way around.

I think there are many reasons (some of which are listed in the wake lock use cases draft) for which the system wake lock should not be postponed.

[marcoscaceres]

Taking this at face value, the proposals to do levels sounds reasonable. And would allow the spec to progress along the Rec track - and hopefully I can convince more of my colleagues at Mozilla that wake locks is something we should implement... or they will convince me otherwise! 😂😭

But, I have two things I'd really like us to consider before moving forward:

1. As a Working Group, we should try to convince other browser vendors that "system" and other locks add value to the platform. Or, alternatively, we should look at "what are we really trying to achieve" with those lock types: The "Starbucks" use case for wake lock was really compelling, because it gave us a real user story that everyone could relate to (the social anxiety was easily transferable to anyone who has ever boarded a plane, or tried to get into an EventBrite event, with a digital barcode).

For new wake locks, I think we need to create a simple document similar to https://www.w3.org/TR/wake-lock-use-cases/ - that shows real use cases/apps, but it doesn't try to force a solution... and find our "Starbucks use case" for the other locks. What I'd like us to get to is, "users are in situations where they are trying to do X, but Y is happening because the platform lacks Z... and that's sad". If we can see what the "Y" is, we can then decide if a particular wake lock is a solution.

Right now, it feels like we are trying to add the other locks because Android has them - but not because there are strong compelling reasons to do so (at least, I don't have anything I can sell internally where people go - "oh, yeah! that happens all the time and it's terrible. We NEED that in the platform!"). Or, put differently, we have a bunch of solutions ("cpu", "system", "wifi", whatever) looking for a problem.

2. Level'ed specs can be hard to maintain because "levels" usually contain all the stuff from previous levels. This makes them a bit of a nightmare to maintain, because any changes we make to L1, we need to propagate to other levels too (this becomes a mess as each level start to diverge, and without really careful planning on how the document is structured). So, it might instead be good to:

• incubate new lock types in Pull Requests - PR Preview lets interested parties see what's being added, and it takes away some of the maintenance burden (but still a bit painful).
• Spin up a separate doc for the new wake locks. Incubate/socialize the new wake locks and see if we can get other folks interested. The just publish the new wake lock independently of the original spec.

In all case, the W3C Process will prevent us from advancing these docs along the Rec Track due to it being of single implementer interest. Like all of us here, I'd like for us to work to overcome that.

[anssiko]

@hadriann: If I understand correctly, that would mean to tailor a specification based on an implementation - while usually things are the other way around.

The W3C process requires "adequate implementation experience" to enter Proposed Rec stage. "Adequate" means two or more interoperable implementations in practice. If implementers choose to implement only a subset of the spec, then that in practice defines the scope that has "adequate implementation experience". The spec has technically been at Candidate Rec (revised CR is due) for over 2 years so this requirement kicks in at next advancement and will block us progressing further unless addressed (possible solutions discussed below). Some say this approach means the spec reflects reality.

I'm sympathetic to the alternative viewpoint, but the following data supports the proposal to advance the screen wake lock feature on its own:

Screen wake lock:

• strong use cases
• one implementation shipping experimentally w/ positive web developer feedback
• another implementer possibly interested

System wake lock:

• no strong use cases
• no implementation(s)

@reillyeon @marcoscaceres re Levels:

I'd like us to choose a path that makes the editing task the least painful for the editors and makes it easiest to gain more implementation experience, in practice addresses Mozilla's concerns in the most fitting way possible.

"Spin up a separate doc for the new wake locks" sounds like the path of least resistance to me. We can integrate the system wake lock spin-off back if more interest emerges. The spin off could live in the same repo to keep things simple.

Alternative approach is to keep both the "screen" and "system" wakelocks in the same spec as currently but annotate "system" wake lock as at risk feature so that it can be dropped without penalty when transitioning from (republished) CR to PR.

[marcoscaceres]

"Spin up a separate doc for the new wake locks" sounds like the path of least resistance to me.

Agree. And, I'd be happy to keep helping with review or whatever we need.

@reillyeon, what say you? Happy to got with whatever y'all think is best.

[reillyeon]

If y'all are happy with something less formal than "levels" then I'm happy to avoid unnecessary bureaucracy. I dislike the idea of incubating in PRs because while I agree it has a lower maintenance burden it is still terribly confusing to keep track of who is proposing what.

I absolutely agree that we need to put together a strong set of use cases for non-screen types of wake locks. I have ideas but I'd like to get screen wake locks into good shape before I contribute to distracting people with them.

We can incubate additional wake lock types in a separate document and merge them into the main specification only when we have a similarly clear vision to what we have today for screen wake locks.

[marcoscaceres]

If y'all are happy with something less formal than "levels" then I'm happy to avoid unnecessary bureaucracy. I dislike the idea of incubating in PRs because while I agree it has a lower maintenance burden it is still terribly confusing to keep track of who is proposing what.

I acknowledge it can be difficult, and stuff can "die on the vine". However, it does often work quite effectively when the PRs capture the right people's attention.

I absolutely agree that we need to put together a strong set of use cases for non-screen types of wake locks. I have ideas but I'd like to get screen wake locks into good shape before I contribute to distracting people with them.

We can incubate additional wake lock types in a separate document and merge them into the main specification only when we have a similarly clear vision to what we have today for screen wake locks.

Sounds like a plan!

[anssiko]

Sent to the list: CfC: split Wake Lock API spec into two, review by 6 Mar 2020

Please provide your 👍 here to signal support. For any concerns, please provide your comments in here too.

[anssiko]

The CfC to split Wake Lock API into two passed.

My proposal would be to gut the system wake lock part out of the current spec and move it into a separate file in this repo, cross-link as appropriate.

@kenchris is the editor, so maybe he can help implement the split.