Skip to content

Commit 739b279

Browse files
committed
Add a section on "Risky changes" to the working mode
This attempts to capture the best practice discussed in whatwg/html#11102 (comment).
1 parent 082e524 commit 739b279

File tree

1 file changed

+14
-0
lines changed

1 file changed

+14
-0
lines changed

Working Mode.md

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -100,6 +100,20 @@ Any change that represents a removal needs to meet these additional criteria:
100100

101101
EXAMPLE: Adjusting existing tests can be difficult. If necessary, an issue can be filed instead to track updating those tests. This was done in [w3c/web-platform-tests#5053](https://github.com/w3c/web-platform-tests/issues/5053) which accompanied the removal in [whatwg/html#2402](https://github.com/whatwg/html/pull/2402).
102102

103+
### Risky changes
104+
105+
Some changes have compatibility risks, which can make it hard to tell whether they'll succeed before they have shipped across multiple implementations.
106+
107+
To balance between having the standard reflect agreed-upon changes, and avoiding prematurely making changes that might need to be reverted, the following guidelines are recommended:
108+
109+
* If multiple implementers are making the changes to their implementations with the intent to ship, then it's best to merge the change into the standard, assuming success. If the change turns out not to be web-compatible, it can later be reverted.
110+
111+
EXAMPLE: [Escape "<" and ">" when serializing attribute values](https://github.com/whatwg/html/pull/6362) was merged once it became clear that all implementations were moving toward shipping, even before the change had reached any implementation's stable channel.
112+
113+
* If multiple implementers are supportive of the change, but only a single implementation is taking the lead by shipping it, then it's best to wait until there's a deployed implementation that's seen significant user testing before merging into the standard.
114+
115+
EXAMPLE: [Removing mutation events](https://github.com/whatwg/html/pull/10573) had support from all implementations, but was not merged until Chromium had shipped the behavior to its stable channel users [for a month](https://github.com/whatwg/dom/issues/305#issuecomment-2302407051). Even then, we kept the tracking issue open until [Chromium removed some mechanisms](https://github.com/whatwg/dom/issues/305#issuecomment-2779845660) that allowed sites to opt back in to mutation events.
116+
103117
## New proposals
104118

105119
As described above, the criteria for inclusion in a WHATWG standard is rather strict. In the initial stages of feature development for the web platform, such widespread implementer support is often not available, or the shape of a feature is not yet clear enough for implementers to feel comfortable pledging their support.

0 commit comments

Comments
 (0)