Repository navigation
What happens to features that do not get enough implementation in CR? #1944
Description
The title tells it all...
In an average W3C Recommendation process, the answer to this question would be to remove this feature from the specification. However, the backward compatibility requirement of our charter forbids us to remove an existing feature (unless is is specifically 3.3 only), hence the question in the issue.
This question must have a clean answer before we ask for a transition request.
I copy this issue to Ralph Swick (@swickr) because his opinion is crucial on what we propose to do.
Activity
dauwhe commentedon Nov 30, 2021
Just for reference, here's what the process document has to say about implementation experience
dlazin commentedon Nov 30, 2021
Clarification: are we talking only about the MUSTs, or all the normative statements?
My thinking is that un(der)implemented MUSTs should be dropped to SHOULDs, at least until we get to the future when they may have better implementation.
Similarly, probably the unimplemented SHOULDs should drop to MAYs.
iherman commentedon Dec 1, 2021
Only the MUSTs.
iherman commentedon Dec 1, 2021
At this point we have two formal terms for our "unsupported" features, and my own interpretation of what they mean (the current spec does not talk about the possible migration paths of such features. Maybe it should.):
Legacy features: they are in the content document to avoid backward compatibility issues with content, but RS-s MUST NOT implement them, and their specification is not part of EPUB 3.3 (they are only defined by reference to older specifications). But authors MAY use them, ie, it is not an error to have them as far as epubcheck is concerned.
This or a future WG may decide to completely remove (some of) them from the specification.
Deprecated features: RS-s MAY implement them (as opposed to legacy features) but authors are actively discouraged (SHOULD NOT) use them.
Deprecated features are not planned to "return" to bona fide standard features by this or a future WG. This or a future WG may decide to completely remove some of them from the specification or, as some sort of intermediate stage, to become legacy features.
(See also §A Unsupported Features in the current spec. There may be discussion on whether the current description is correct and whether the migration path should be more precisely documented.)
I think that neither of these two categories really fit the case listed in the issue. An unimplemented feature has been put forward as a standard feature because the WG thinks it is essential; one can hope that, at some point, there will be enough implementations. I think therefore that we may want to have a third category of features:
Optional features are such that authors MAY use them and RS-s SHOULD implement them.
A future WG may decide to turn such a feature into a deprecated feature (if all hope is lost to get it implemented) or promote it into a bona fide standard feature (if the implementation landscape changes).
The answer of the original question would then be: if a feature does not pass the CR bar, then it is "demoted" to an optional feature. This does not harm backward compatibility.
I am not sure what we would expect EPUB Check to do with optional features. My gut feeling is that a warning would be in order when using them, but my understanding is that many digestion pipelines make no difference in practice between error and warning messages. Maybe a separate flag on epubcheck, listing optional features, is a possible way out.
iherman commentedon Dec 3, 2021
The issue was discussed in a meeting on 2021-12-03
List of resolutions:
View the transcript
2.1. What happens to features that do not get enough implementation in CR? (issue epub-specs#1944)
See github issue epub-specs#1944.
Dave Cramer: the point of the W3C process is to show that features are implementable by writing tests and showing that that test can be passed by more than 1 independent implementation.
… so, where we don't find implementations, what then?.
… and how do we balance against our need for backwards compatibility.
Ivan Herman: the usual approach is to say that in a normative statement doesn't have enough implementations it is removed from spec.
… we cannot do this because of backwards compatibility.
… we have to resolve this before we go to CR.
… there are 2 categories already used for features that are not entirely okay. 1) "Legacy" (e.g. NCX) which are there in the spec because people may still want to use EPUB2. These are not defined in our spec..
… currently we say RS MUST NOT implement them, and users MAY use them.
… so no error or warning if found in an epub.
… "Deprecated" features are ones that were in earlier versions of epub3, but were not implemented. Authors are discouraged from using them ("SHOULD NOT" use), and RS MAY implement them.
… I think none of the two are a good fit for answering this issue.
… the feeling is that legacy features may disappear from future versions of epub.
… deprecated is saying that we are discouraging users from using them, and this may be a strong statement because we may still hope that some of the features that lack implementation today may find implementations in the near future.
… I think we should introduce a 3rd option, yet to be defined, maybe "Optional". Something that authors may use, and RS should implement..
… i.e., they are not normative, but maybe in a later version of spec they may become normative.
… (and we'd remove the optional classification at that point).
Matt Garrish: generally agree, but wanted to clarify that we're not going to start labelling new things as legacy.
… only epub 2 things can be legacy.
… and agree that we're not going to start deprecating things that we still want to keep alive.
Dave Cramer: its hard to talk about this in the abstract.
… so using fallback as an example, my understanding is that the feature as described is not implemented anywhere, yet it affects rendering of epubs today.
… i don't like the idea of Optional because it gives the wrong impression; if a feature isn't implemented, then it doesn't work, and you shouldn't use it.
… not sure what we should do, but I don't want to leave things in the spec without discouraging people from using them.
Brady Duga: Google Play supports fallbacks btw.
… but maybe "At Risk"?.
Ivan Herman: "At Risk" has a specific meaning within W3C process.
Brady Duga: okay, then something at suggests the risk of using those features that have not received implementations then.
Dan Lazin: I think Optional and May have the same normative meaning, but May implies "you can do this" while Optional implies "you can do this, but not sure why you would".
… so can we just use May instead?.
Ivan Herman: the exact word we use to label these sorts of features is kind of an editorial question, we need to decide whether we need a category for these.
Dave Cramer: and what would epubcheck do with these?.
Dave Cramer: i think we should continue to align with epubcheck on these issues. So if we introduce a new category, there should be a corresponding category of flag in epubcheck.
… based on the tests we've done so far, what else might end up in this category?.
Wendy Reid: the reading system object.
Dave Cramer: i think ibooks does something with that?
Brady Duga: i thought it was implemented among RS that support scripting.
Wendy Reid: some of the FXL properties, like mixed layouts (i.e. where a single book has fixed and reflow content).
Ivan Herman: we have to specify what happens to these features in advance of CR.
Dave Cramer: we will be influenced in our decision based on what sorts of features will fall into this bucket, as determined by testing results.
Ivan Herman: that's kind of chicken and egg.
… and are we sure that all package metadata are used by enough publishers?.
… today there are some properties that are deprecated, might be the case with some of the properties we still have.
Dave Cramer: given that this is about CR exit criteria, this depends on the judgement of the Director.
… do we have any sense of what the feeling is, especially given all the history of epub.
Ivan Herman: I have a weekly meeting with that level of the W3C, so the channel of communication is open.
… to be specific, I think we should add a 3rd category in appendix A (beside legacy and deprecated), and make it clear that this category is meant for features that we don't want to deprecate, but authors must use with care due to their risky status.
… I can present this to the Director.
Matt Garrish: is there a timeline for this? When is the classification determined?.
Ivan Herman: when we leave CR.
… so the classification will be valid for the next recommendation.
Matt Garrish: so should we say that these features have been given a pass for this version, but that they might be deprecated in the next version if we don't find additional support?.
Dave Cramer: we've gotten into trouble with this sort of thing in the past. Don't want to say what will happen in future..
George Kerscher: are these experimental features we'd like to see implemented? Or is this something that we want to get rid of?.
Dave Cramer: unclear, the testing would answer those questions. There won't necessarily be any sort of pattern. Obviously we thought all the features were good ideas at the time we wrote them.
Charles LaPierre: what is the difference between "risky" and "at risk" if we're applying these labels at the point we go into Rec?.
Dave Cramer: at risk is a term of art in W3C, could cause backwards compatibility issues.
Ivan Herman: if we label something "at risk", then the usual view is that we're required to remove that feature from spec before Rec, and we cannot do this because of the backwards compat mandate.
… if something is simply "risky", then its up to us whether to remove it.
Dave Cramer: seems to be consensus that we need 3rd category, though the language is to be determined, it would be tied to epubcheck with a flag that is something less severe than a warning.
Ivan Herman: who has the action on #1944?.
Matt Garrish: I can take it, starting with the name "risky".
mattgarrish commentedon Dec 3, 2021
What about just calling these "beta" features?
dauwhe commentedon Dec 3, 2021
Does that imply they will be supported in the future?
mattgarrish commentedon Dec 3, 2021
I've only ever taken beta to mean use at your own risk. There's no guarantee if or when a beta feature will ever be fully implemented.
I'm just having trouble writing "risky" with a straight face because I have a picture in my head of exploding epubs. 😄
mattgarrish commentedon Dec 6, 2021
The new "risky" class has been implemented in #1953, but the question of whether it remains the right name remains an open question.
A couple of additional names to come out of the PR are:
rdeltour commentedon Dec 6, 2021
Another name I thought about is "impractical". But it may sound more definitive than "unproven" or "incubated", so I'm not sure it's better.
mattgarrish commentedon Dec 6, 2021
Without knowing what all we're going to label, I don't like labels that sound like they're making a judgement on their future status. (If something is impractical, for example, why isn't it deprecated?)
Incubated might need to be "incubating" otherwise it sounds like we're done. If I have to find fault with it, it's odd to say we're incubating features that have been in use for 10 years, but it also has the benefit of being neutral about the future.
"Unstable" might be another choice. It's a bit more neutral way of saying that use is risky.
iherman commentedon Dec 7, 2021
Indeed, I think "impractical" sends the wrong message.
True for "incubated" -> "incubating" . As for the the 10 years incubating: that is the honest truth after all... But I see the point.
We seem to have, in lexical order:
I have the impression that the choice among these three is becoming a matter of taste; personally, I could live with any of those three. Maybe we should simply get a vote out there, leave it open for, say, a week, and get it over with? Or do we want to live in a benevolent dictatorship and let the chairs decide?
@dauwhe @wareid @shiestyle
shiestyle commentedon Dec 8, 2021
Let's discuss it on chairs' call.
iherman commentedon Dec 10, 2021
The issue was discussed in a meeting on 2021-12-09
View the transcript
5. Bikeshedding – what to call features without enough implementation?
See github issue epub-specs#1944.
Wendy Reid: continuing our discussion from last week - what do we call the features that don't get enough implementation?.
… we've used deprecated in the past (not what HTML spec goes by), and we've also used legacy.
Dave Cramer: legacy features are holdovers from EPUB2 that are still useful, e.g. for making EPUB3 backwards compatible with EPUB2 RS.
… this is a different situation.
… this is a collision between W3C process whereby we need demonstrable implementation of features (i.e. tests), but we also have a charter where we can't invalidate existing content.
… so what if there's something in the spec where we don't have 2 passing tests now, but the implementations could exist in the future.
Theresa O'Connor: i don't know the details of the charter restriction. If epubcheck would have said "this is fine" before, then it needs to keep saying that? Even if no one had implemented the feature?.
Dave Cramer: yes, that's basically my understanding, since we live in an ecosystem where even a warning from epubcheck will block content from reaching users.
… and we can't rely on people updating content.
Theresa O'Connor: in HTML we might call a feature obsolete, and then obsolete features can itself be conforming or non-conforming.
… i think it would be fine to call your features obsolete, but the spec needs to have specific text directed to conformance checkers asking them not to throw warnings.
… like obsolete but conforming.
… in the W3C process when you reach CR you have to list features at risk, and typically those are the ones where you don't have enough implementations, but where you hope to get those implementations during CR.
… so, actually, yeah... if you don't want to maybe end up dropping those features at the end of CR, then i'd go back to my first suggestion.
Dave Cramer: epubcheck already has an informative level of alert below warning.
… we could say to use this level.
Theresa O'Connor: typically things in W3C are less tied to a specific conformance checker, but clearly epubcheck is the reality for epubs.
… you want to make your spec a little more general, but you can have a specific statement about epubcheck.
Dave Cramer: we also don't want to send false messages about what is and is not well supported.
Theresa O'Connor: one of the ways that HTML handles that for obsolete features, is that in the main text of the spec it doesn't even mention them.
… they're defined in a separate obsolete features section at the end.
… if a feature like that is presented right in the main text and not visually distinct, then people will of course believe that those features are just as sound.
… so maybe consolidate them and make them visually distinct.
Brady Duga: i liked at risk, but ivan didn't like it because at risk had a specific meaning in W3C process.
… deprecated doesn't seem to fit. Maybe something scarier like imperilled..
… and we should make sure that conformance checkers can fail epubs that contain these at the user's option.
… even if it isn't the checker's default behaviour.
Theresa O'Connor: imperiled is a bit obscure for non-native speakers.
… obsolete and deprecated are more recognizable in the world of spec writing.
… but I see duga's point that at risk scares people off more effectively than either of the other terms.
Brady Duga: also these features might actually become used some day, where as deprecated feels almost like the opposite.
Theresa O'Connor: right, if you get more implementations they could just become regular features.
… reminds me of speculative features for browsers, where you have one good implementation, but then it just gets stuck in feature limbo for a while.
… might be worth reaching out to YCG chairs to ask what they're doing.
Brady Duga: we could do something like "experimental" (but it would be weird to have manifest fallbacks become experimental).
Wendy Reid: i like experimental, but I also like the idea of reaching out to YCG chairs to ask for advice.
Dave Cramer: also incubating, unproven, or unstable - but i'm not wild about these.
Theresa O'Connor: aside from the question of naming, it sounds like everyone is on the same page about how to describe these types of features, and what the behavior of conformance checkers should be, so it seems like you're in a pretty good place.
Dave Cramer: i think we a lot more good info on our goals, and how HTML has handled this.
… we'll ask around for advice about naming.
Brady Duga: maybe we could go for a Japanese name?.
Murata Makoto: no specific ideas right now.
iherman commentedon Jan 21, 2022
The issue was discussed in a meeting on 2022-01-20
List of resolutions:
View the transcript
2. Bikeshed name for underimplemented features.
See github issue epub-specs#1944.
Wendy Reid: we have the unique problem that this is a 20 y/o spec, but with some features that were either not implemented at all, or only rarely.
… so they technically do not qualify for rec track doc.
Wendy Reid: but we can position those features in a special category that we don't want to remove from spec just yet, but which may not be supported.
… we just need to decide what to call this category.
… so we can refer to them in the CR transition document.
Dan Lazin: i think the correct name is 'at risk features'. Seems to include both new and old underimplemented features.
Wendy Reid: 'at risk' is a conflict with technical terms used in the W3C process document.
Dan Lazin: does this apply to both new and old underimplemented features?.
Wendy Reid: we don't have anything new that is underimplemented.
Brady Duga: not much is new at this point.
Wendy Reid: i like frozen.
Murata Makoto: in ISO we use the term stabilized - i.e. we are not going to touch the spec.
Dan Lazin: 'legacy features'?.
Wendy Reid: legacy is already used in the spec for features that are holdovers from EPUB2 - e.g. NCX.
… they should still be supported, but we don't encourage their use.
Brady Duga: 'cutting edge' - because they are RELATIVELY new.
Wendy Reid: the other part of the naming is that the name needs to be relatively well known.
Dan Lazin: okay, 'throwback' then?.
… 'archived'?.
… the thing about frozen that i don't love is that it seems like we promise we aren't touching them, but we actually might polish them up in the future if an urgent need arises.
Wendy Reid: 'parked'?.
… we don't want to discourage RS implementors from implementing these features, but we don't want authors to rely on them working.
Shinya Takami (高見真也): 'unpopular'.
Wendy Reid: there are popular ideas in this category that just never took over.
Dan Lazin: so just 'under implemented' then.
Wendy Reid: we are never going to test every RS, so when we say something is under implemented because it doesn't meet the W3C testing threshold, we don't really know.
Wendy Reid: seems like maybe under implemented is our winner?.
Dan Lazin: the internet really thinks it should be hyphenated, but i like it with no hyphen (no space).
Dan Lazin: are we specifically saying that it doesn't meet 2? Or just that authors should not use these features because they are not used by the mainstream?.
Wendy Reid: for the W3C priority of implementor doesn't matter.
Dan Lazin: for the benefit of our users should we use this category as a warning for features not in the mainstream?.
Wendy Reid: not sure we should get into that, politics, etc..
Wendy Reid: great, this will help us write our CR exit criteria.