Skip to content

Commit 84d6ebc

Browse files
tabatkinstabatkins
committed
[css-2015] indentation
1 parent 48d5485 commit 84d6ebc

File tree

1 file changed

+157
-157
lines changed

1 file changed

+157
-157
lines changed

‎css-2015/Overview.bs

+157-157
Original file line numberDiff line numberDiff line change
@@ -391,163 +391,163 @@ Requirements for Responsible Implementation of CSS</h2>
391391
the CSSWG recommends the following best practices for the implementation of
392392
<a>unstable</a> features and <a>proprietary extensions</a> to CSS:
393393

394-
<h4 id="experimental">
395-
Experimentation and Unstable Features</h4>
396-
397-
Issue: Rewritten per gregwhitworth's feedback.
398-
399-
Implementations of <a>unstable</a> features
400-
that are described in W3C specifications
401-
but are not interoperable
402-
should not be released broadly for general use;
403-
but may be released for limited, experimental use in controlled environments.
404-
405-
<details class=why>
406-
<summary>Why?</summary>
407-
We want to allow both authors and implementors to experiment with the feature and give feedback,
408-
but prevent authors from relying on them in production websites
409-
and thereby accidentally "locking in" (through content dependence)
410-
certain syntax or behavior that might change later.
411-
</details>
412-
413-
<div class="example">
414-
For example,
415-
a UA could release an <a>unstable</a> features for experimentation
416-
through beta or other testing-stage builds;
417-
behind a hidden configuration flag;
418-
behind a switch enabled only for specific testing partners;
419-
or through some other means of limiting dependent use.
420-
</div>
421-
422-
A CSS feature is considered <dfn>unstable</dfn> until
423-
its specification has reached the Candidate Recommendation (CR) stage in the W3C process.
424-
In exceptional cases,
425-
the CSSWG may additionally, by an officially-recorded resolution,
426-
add pre-CR features to the set that are considered safe to release for broad use.
427-
428-
Note: Vendors should consult the WG explicitly and not make assumptions on this point,
429-
as a pre-CR spec that hasn't changed in awhile is usually more out-of-date than stable.
430-
431-
432-
<h4 id="proprietary">
433-
Proprietary and Non-standardized Features</h4>
434-
435-
Issue: Rewritten as open vs. closed systems instead of Web vs. non-Web, per szilles' request.
436-
437-
A CSS feature is a <dfn>proprietary extension</dfn> if it is meant for use
438-
in a closed environment accessible only to a single vendor's user agent(s).
439-
A UA should support such <a>proprietary extensions</a>
440-
only through a vendor-prefixed syntax
441-
and not expose them to open (multi-UA) environments such as the World Wide Web.
442-
443-
<details class=why>
444-
<summary>Why?</summary>
445-
The prefixing requirement allows shipping specialized features in closed environments
446-
without conflicting with future additions to standard CSS.
447-
The restriction on exposure to open systems is to prevent
448-
accidentally causing the public CSS environment
449-
to depend on an unstandardized <a>proprietary extensions</a>.
450-
</details>
451-
452-
<div class="example">
453-
For example,
454-
Firefox's XUL-based UI, Apple's iTunes UI, and Microsoft's Universal Windows Platform app
455-
use extensions to CSS implemented by their respective UAs.
456-
So long as these UAs do not allow Web content to access these features,
457-
they do not provide an opportunity for such content
458-
to become dependent on their <a>proprietary extensions</a>.
459-
</div>
460-
461-
Even if a feature is intended to eventually be used in the Web,
462-
if it hasn't yet been standardized
463-
it should still not be exposed to the Web.
464-
465-
466-
<h4 id="de-facto">
467-
Market Pressure and De Facto Standards</h4>
468-
469-
Issue: Added "should not" against encumbered features, per dbaron's request.
470-
471-
If a feature is <a>unstable</a>, yet
472-
473-
* at least three UAs implement the feature
474-
(or a UA has broken the other rules and shipped for broad use
475-
an <a>unstable</a> or otherwise non-standard feature in a production release),
476-
* <em>and</em> the implementations have rough interoperability,
477-
* <em>and</em> the CSS Working Group has recorded consensus
478-
that this feature should exist and be released,
479-
480-
implementers may ship that feature unprefixed in broad-release builds.
481-
<dfn>Rough interoperability</dfn> is satisfied by a subjective judgment
482-
that even though there may be differences,
483-
the implementations are sufficiently similar
484-
to be used in production websites for a substantial number of use cases.
485-
486-
<details class=why>
487-
<summary>Why?</summary>
488-
If a feature is sufficiently popular that three or more browsers have implemented it before it's finished standardization,
489-
this clause allows releasing the pressure to ship.
490-
Also, if a feature has already escaped into the wild and sites have started depending on it,
491-
pretending it's still "experimental" doesn't help anyone.
492-
Allowing others to ship unprefixed recognizes that the feature is now de facto standardized
493-
and encourages authors to write cross-platform code.
494-
495-
<p>Note, though, that the CSSWG must still be consulted to ensure coordination across vendors
496-
and to ensure sanity review by the CSS experts from each vendor.
497-
Note also that <a>rough interoperability</a> still usually means
498-
painful lack of interop in edge (or not-so-edge) cases,
499-
particularly because details have not been ironed out through the standards review process.
500-
</details>
501-
502-
<p>When exposing such an <a>unstable</a> feature to the Web in a production release,
503-
implementations should support both prefixed and unprefixed syntaxes
504-
for the feature.
505-
Once the feature has stabilized and the implementation is updated to match interoperable behavior,
506-
support for the prefixed syntax should be removed.
507-
508-
Note: Anyone promoting <a>unstable</a> features to authors
509-
is urged to describe them
510-
through their standard unprefixed syntax,
511-
and to avoid encouraging the use of the prefixed syntax
512-
for any purpose other than working around implementation differences.
513-
514-
<details class=why>
515-
<summary>Why?</summary>
516-
This is recommended so that authors can use the unprefixed syntax to target all implementations,
517-
but when necessary, can target specific implementations
518-
to work around incompatibilities among implementations
519-
as they get ironed out through the standards/bugfixing process.
520-
521-
Some authors unfamiliar with this approach
522-
and accustomed to the earlier practice
523-
of shipping unstable features only under a prefix
524-
may fail to notice that using the unprefixed syntax
525-
is sufficient to target all implementations,
526-
and may therethore include the prefixed syntax
527-
of the various vendors
528-
followed by the unprefixed syntax.
529-
530-
Even in the face of this possible misuse,
531-
this approach still beneficial.
532-
The lack of a phase
533-
where only the prefixed syntax is supported
534-
greatly reduces the risk of stylesheets
535-
targetting only this prefixed syntax being written.
536-
This in turn allows UA vendors to retire
537-
their prefixed syntax once the feature is stable,
538-
without risking breaking existing content.
539-
It also reduces the need occasionally felt by by some vendors
540-
to support a feature with the prefix of another vendor,
541-
due to content depending on that syntax.
542-
</details>
543-
544-
In order to preserve the open nature of CSS as a technology,
545-
vendors should make it possible for other implementors
546-
to freely implement any features that they do ship.
547-
To this end, they should provide spec-editing and testing resources
548-
to complete standardization of such features,
549-
and avoid other obstacles (e.g., platform dependency, licensing restrictions)
550-
to their competitors shipping the feature.
394+
<h4 id="experimental">
395+
Experimentation and Unstable Features</h4>
396+
397+
Issue: Rewritten per gregwhitworth's feedback.
398+
399+
Implementations of <a>unstable</a> features
400+
that are described in W3C specifications
401+
but are not interoperable
402+
should not be released broadly for general use;
403+
but may be released for limited, experimental use in controlled environments.
404+
405+
<details class=why>
406+
<summary>Why?</summary>
407+
We want to allow both authors and implementors to experiment with the feature and give feedback,
408+
but prevent authors from relying on them in production websites
409+
and thereby accidentally "locking in" (through content dependence)
410+
certain syntax or behavior that might change later.
411+
</details>
412+
413+
<div class="example">
414+
For example,
415+
a UA could release an <a>unstable</a> features for experimentation
416+
through beta or other testing-stage builds;
417+
behind a hidden configuration flag;
418+
behind a switch enabled only for specific testing partners;
419+
or through some other means of limiting dependent use.
420+
</div>
421+
422+
A CSS feature is considered <dfn>unstable</dfn> until
423+
its specification has reached the Candidate Recommendation (CR) stage in the W3C process.
424+
In exceptional cases,
425+
the CSSWG may additionally, by an officially-recorded resolution,
426+
add pre-CR features to the set that are considered safe to release for broad use.
427+
428+
Note: Vendors should consult the WG explicitly and not make assumptions on this point,
429+
as a pre-CR spec that hasn't changed in awhile is usually more out-of-date than stable.
430+
431+
432+
<h4 id="proprietary">
433+
Proprietary and Non-standardized Features</h4>
434+
435+
Issue: Rewritten as open vs. closed systems instead of Web vs. non-Web, per szilles' request.
436+
437+
A CSS feature is a <dfn>proprietary extension</dfn> if it is meant for use
438+
in a closed environment accessible only to a single vendor's user agent(s).
439+
A UA should support such <a>proprietary extensions</a>
440+
only through a vendor-prefixed syntax
441+
and not expose them to open (multi-UA) environments such as the World Wide Web.
442+
443+
<details class=why>
444+
<summary>Why?</summary>
445+
The prefixing requirement allows shipping specialized features in closed environments
446+
without conflicting with future additions to standard CSS.
447+
The restriction on exposure to open systems is to prevent
448+
accidentally causing the public CSS environment
449+
to depend on an unstandardized <a>proprietary extensions</a>.
450+
</details>
451+
452+
<div class="example">
453+
For example,
454+
Firefox's XUL-based UI, Apple's iTunes UI, and Microsoft's Universal Windows Platform app
455+
use extensions to CSS implemented by their respective UAs.
456+
So long as these UAs do not allow Web content to access these features,
457+
they do not provide an opportunity for such content
458+
to become dependent on their <a>proprietary extensions</a>.
459+
</div>
460+
461+
Even if a feature is intended to eventually be used in the Web,
462+
if it hasn't yet been standardized
463+
it should still not be exposed to the Web.
464+
465+
466+
<h4 id="de-facto">
467+
Market Pressure and De Facto Standards</h4>
468+
469+
Issue: Added "should not" against encumbered features, per dbaron's request.
470+
471+
If a feature is <a>unstable</a>, yet
472+
473+
* at least three UAs implement the feature
474+
(or a UA has broken the other rules and shipped for broad use
475+
an <a>unstable</a> or otherwise non-standard feature in a production release),
476+
* <em>and</em> the implementations have rough interoperability,
477+
* <em>and</em> the CSS Working Group has recorded consensus
478+
that this feature should exist and be released,
479+
480+
implementers may ship that feature unprefixed in broad-release builds.
481+
<dfn>Rough interoperability</dfn> is satisfied by a subjective judgment
482+
that even though there may be differences,
483+
the implementations are sufficiently similar
484+
to be used in production websites for a substantial number of use cases.
485+
486+
<details class=why>
487+
<summary>Why?</summary>
488+
If a feature is sufficiently popular that three or more browsers have implemented it before it's finished standardization,
489+
this clause allows releasing the pressure to ship.
490+
Also, if a feature has already escaped into the wild and sites have started depending on it,
491+
pretending it's still "experimental" doesn't help anyone.
492+
Allowing others to ship unprefixed recognizes that the feature is now de facto standardized
493+
and encourages authors to write cross-platform code.
494+
495+
<p>Note, though, that the CSSWG must still be consulted to ensure coordination across vendors
496+
and to ensure sanity review by the CSS experts from each vendor.
497+
Note also that <a>rough interoperability</a> still usually means
498+
painful lack of interop in edge (or not-so-edge) cases,
499+
particularly because details have not been ironed out through the standards review process.
500+
</details>
501+
502+
<p>When exposing such an <a>unstable</a> feature to the Web in a production release,
503+
implementations should support both prefixed and unprefixed syntaxes
504+
for the feature.
505+
Once the feature has stabilized and the implementation is updated to match interoperable behavior,
506+
support for the prefixed syntax should be removed.
507+
508+
Note: Anyone promoting <a>unstable</a> features to authors
509+
is urged to describe them
510+
through their standard unprefixed syntax,
511+
and to avoid encouraging the use of the prefixed syntax
512+
for any purpose other than working around implementation differences.
513+
514+
<details class=why>
515+
<summary>Why?</summary>
516+
This is recommended so that authors can use the unprefixed syntax to target all implementations,
517+
but when necessary, can target specific implementations
518+
to work around incompatibilities among implementations
519+
as they get ironed out through the standards/bugfixing process.
520+
521+
Some authors unfamiliar with this approach
522+
and accustomed to the earlier practice
523+
of shipping unstable features only under a prefix
524+
may fail to notice that using the unprefixed syntax
525+
is sufficient to target all implementations,
526+
and may therethore include the prefixed syntax
527+
of the various vendors
528+
followed by the unprefixed syntax.
529+
530+
Even in the face of this possible misuse,
531+
this approach still beneficial.
532+
The lack of a phase
533+
where only the prefixed syntax is supported
534+
greatly reduces the risk of stylesheets
535+
targetting only this prefixed syntax being written.
536+
This in turn allows UA vendors to retire
537+
their prefixed syntax once the feature is stable,
538+
without risking breaking existing content.
539+
It also reduces the need occasionally felt by by some vendors
540+
to support a feature with the prefix of another vendor,
541+
due to content depending on that syntax.
542+
</details>
543+
544+
In order to preserve the open nature of CSS as a technology,
545+
vendors should make it possible for other implementors
546+
to freely implement any features that they do ship.
547+
To this end, they should provide spec-editing and testing resources
548+
to complete standardization of such features,
549+
and avoid other obstacles (e.g., platform dependency, licensing restrictions)
550+
to their competitors shipping the feature.
551551

552552

553553
<h3 id="testing">Implementations of CR-level Features</h3>

0 commit comments

Comments
 (0)