From 642f9267df365fee958e4348b9be609b5a92313e Mon Sep 17 00:00:00 2001 From: Jeffrey Yasskin Date: Thu, 18 Sep 2025 03:04:32 +0000 Subject: [PATCH 01/14] Rewrite the "removing features" section, incorporating "Support Existing Content" from the HTTP Design Principles --- index.bs | 50 +++++++++++++++++++++++++++++++++++--------------- 1 file changed, 35 insertions(+), 15 deletions(-) diff --git a/index.bs b/index.bs index 29be67e4..a0c01c25 100644 --- a/index.bs +++ b/index.bs @@ -307,22 +307,42 @@ it might still be possible; see [[#removing-features]]. Do not assume that a change or removal is impossible without first checking. -

Remove or change capabilities only once you understand existing usage

- -Prioritize compatibility with existing content when removing or changing functionality. - -Once a significant amount of content has come to depend on a particular behavior, -removing or changing that behavior is discouraged. -Removing or changing features and capabilities is possible, -but it first requires that the nature and scope of the impact on existing content -is well understood. -This might require research into how features are used by existing content. - -The obligation to understand existing usage also applies to any features that content relies upon. +

Prioritize compatibility when changing or removing features

+ +Before changing how a feature behaves, +fully understand how websites are currently using it. +This might require research, +for example by adding metrics to a popular user agent +and/or by [searching the HTTP Archive](https://har.fyi/guides/getting-started/). +Breaking content is harmful, +and the benefit of a change has to +significantly outweigh that harm to be worth doing. + +The obligation to understand existing usage +also applies to non-standardized or unspecified features +that content relies upon. This includes vendor-proprietary features and -behavior that might be considered implementation bugs. -Web features are not solely defined in specifications; -they are also defined by how content uses those features. +implementation bugs. + +Despite this, it is sometimes acceptable +to break some existing content +in order to help a large number of the web's users. +Breakage is more likely to be acceptable if: + +* Only a tiny amount of existing content depend on the feature or behavior. +* Only a tiny number of people see that content. +* The content only appears in test cases or examples. +* The content is currently broken in most recent popular user agents. +* The content is not on the public web, + but is instead found on internal sites + with a controlled user environment. + Beware in this case that internal sites are + often invisible to our analysis tools. + Getting a single complaint is often a sign + of a much larger amount of hidden breakage. +* The benefit of breaking content is very large. + For example, removing old SSL and TLS versions breaks lots of content + but prevents even more security breaches.

Leave the web better than you found it

From 72c6e6d5b7d194be196c050c95fa6b3c571f62b5 Mon Sep 17 00:00:00 2001 From: Jeffrey Yasskin Date: Thu, 18 Sep 2025 03:28:35 +0000 Subject: [PATCH 02/14] Fix indentation. --- index.bs | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/index.bs b/index.bs index a0c01c25..e02b964f 100644 --- a/index.bs +++ b/index.bs @@ -334,15 +334,15 @@ Breakage is more likely to be acceptable if: * The content only appears in test cases or examples. * The content is currently broken in most recent popular user agents. * The content is not on the public web, - but is instead found on internal sites - with a controlled user environment. - Beware in this case that internal sites are - often invisible to our analysis tools. - Getting a single complaint is often a sign - of a much larger amount of hidden breakage. + but is instead found on internal sites + with a controlled user environment. + Beware in this case that internal sites are + often invisible to our analysis tools. + Getting a single complaint is often a sign + of a much larger amount of hidden breakage. * The benefit of breaking content is very large. - For example, removing old SSL and TLS versions breaks lots of content - but prevents even more security breaches. + For example, removing old SSL and TLS versions breaks lots of content + but prevents even more security breaches.

Leave the web better than you found it

From ec1d5a80937ee9547ab24d8072b146c0368a8c2e Mon Sep 17 00:00:00 2001 From: Jeffrey Yasskin Date: Wed, 17 Sep 2025 21:12:58 -0700 Subject: [PATCH 03/14] Apply changes from discussion Co-authored-by: Martin Thomson --- index.bs | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/index.bs b/index.bs index e02b964f..be6a04ec 100644 --- a/index.bs +++ b/index.bs @@ -310,10 +310,10 @@ Do not assume that a change or removal is impossible without first checking.

Prioritize compatibility when changing or removing features

Before changing how a feature behaves, -fully understand how websites are currently using it. -This might require research, +understand how websites are currently using it. +Gaining a good understanding might require research, for example by adding metrics to a popular user agent -and/or by [searching the HTTP Archive](https://har.fyi/guides/getting-started/). +or by [searching the HTTP Archive](https://har.fyi/guides/getting-started/). Breaking content is harmful, and the benefit of a change has to significantly outweigh that harm to be worth doing. @@ -337,7 +337,7 @@ Breakage is more likely to be acceptable if: but is instead found on internal sites with a controlled user environment. Beware in this case that internal sites are - often invisible to our analysis tools. + often invisible to analysis tools designed for public content. Getting a single complaint is often a sign of a much larger amount of hidden breakage. * The benefit of breaking content is very large. From bca8b852df896e6786566fc3777f11974674f12a Mon Sep 17 00:00:00 2001 From: Jeffrey Yasskin Date: Wed, 17 Sep 2025 21:16:04 -0700 Subject: [PATCH 04/14] Say who breakage harms. --- index.bs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/index.bs b/index.bs index be6a04ec..67de8f88 100644 --- a/index.bs +++ b/index.bs @@ -314,7 +314,7 @@ understand how websites are currently using it. Gaining a good understanding might require research, for example by adding metrics to a popular user agent or by [searching the HTTP Archive](https://har.fyi/guides/getting-started/). -Breaking content is harmful, +Breaking content harms users, and the benefit of a change has to significantly outweigh that harm to be worth doing. From 393f52cd78cd78ecd9b1971814ffcf608fe37ba1 Mon Sep 17 00:00:00 2001 From: Jeffrey Yasskin Date: Thu, 18 Sep 2025 04:22:51 +0000 Subject: [PATCH 05/14] Cite the-web-is-unversioned. --- index.bs | 21 ++++++++++++++++++++- 1 file changed, 20 insertions(+), 1 deletion(-) diff --git a/index.bs b/index.bs index 67de8f88..98b00cfe 100644 --- a/index.bs +++ b/index.bs @@ -24,6 +24,24 @@ Required IDs: using-http Link Defaults: html (dfn) queue a task/in parallel/reflect +
+{
+  "the-web-is-unversioned": {
+    "authors": [
+      "Sangwhan Moon",
+      "Amy Guy"
+    ],
+    "href": "https://www.w3.org/2001/tag/doc/the-web-is-unversioned/",
+    "title": "The web is unversioned",
+    "status": "TAG Finding",
+    "publisher": "W3C",
+    "date": "27 March 2025",
+    "deliveredBy": [
+      "https://www.w3.org/groups/other/tag/"
+    ]
+  }
+}
+
 spec:css-cascade-5; type:dfn; text:inherit
 spec:css2; type: property; text: line-height
@@ -316,7 +334,8 @@ for example by adding metrics to a popular user agent
 or by [searching the HTTP Archive](https://har.fyi/guides/getting-started/).
 Breaking content harms users,
 and the benefit of a change has to
-significantly outweigh that harm to be worth doing.
+significantly outweigh that harm to be worth doing
+[[the-web-is-unversioned]].
 
 The obligation to understand existing usage
 also applies to non-standardized or unspecified features

From d575739d95a4b5eeb38363866a3208c8af96f572 Mon Sep 17 00:00:00 2001
From: Jeffrey Yasskin 
Date: Wed, 17 Sep 2025 21:23:47 -0700
Subject: [PATCH 06/14] Make the first paragraph a single sentence.

Co-authored-by: Martin Thomson 
---
 index.bs | 1 +
 1 file changed, 1 insertion(+)

diff --git a/index.bs b/index.bs
index 98b00cfe..21c5a791 100644
--- a/index.bs
+++ b/index.bs
@@ -329,6 +329,7 @@ Do not assume that a change or removal is impossible without first checking.
 
 Before changing how a feature behaves,
 understand how websites are currently using it.
+
 Gaining a good understanding might require research,
 for example by adding metrics to a popular user agent
 or by [searching the HTTP Archive](https://har.fyi/guides/getting-started/).

From f586eb50c534864b903dc95943e6694a87f807b2 Mon Sep 17 00:00:00 2001
From: Jeffrey Yasskin 
Date: Wed, 17 Sep 2025 21:24:05 -0700
Subject: [PATCH 07/14] s/help/improve experience/

Co-authored-by: Martin Thomson 
---
 index.bs | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/index.bs b/index.bs
index 21c5a791..2fa0147a 100644
--- a/index.bs
+++ b/index.bs
@@ -346,7 +346,7 @@ implementation bugs.
 
 Despite this, it is sometimes acceptable
 to break some existing content
-in order to help a large number of the web's users.
+in order to improve the experience for a large number of web users.
 Breakage is more likely to be acceptable if:
 
 * Only a tiny amount of existing content depend on the feature or behavior.

From a61393c2a78680d9556ab071411a0d98efeb3e10 Mon Sep 17 00:00:00 2001
From: Jeffrey Yasskin 
Date: Wed, 17 Sep 2025 21:32:34 -0700
Subject: [PATCH 08/14] s/currently/already/

Co-authored-by: Sarven Capadisli 
---
 index.bs | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/index.bs b/index.bs
index 2fa0147a..d86da287 100644
--- a/index.bs
+++ b/index.bs
@@ -352,7 +352,7 @@ Breakage is more likely to be acceptable if:
 * Only a tiny amount of existing content depend on the feature or behavior.
 * Only a tiny number of people see that content.
 * The content only appears in test cases or examples.
-* The content is currently broken in most recent popular user agents.
+* The content is already broken in most recent popular user agents.
 * The content is not on the public web,
     but is instead found on internal sites
     with a controlled user environment.

From 5b2ffa8b8aeae324782fff6072d216b4f7ffca87 Mon Sep 17 00:00:00 2001
From: Jeffrey Yasskin 
Date: Wed, 17 Sep 2025 21:36:06 -0700
Subject: [PATCH 09/14] s/popular/widely-used/

---
 index.bs | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/index.bs b/index.bs
index d86da287..e53ed961 100644
--- a/index.bs
+++ b/index.bs
@@ -331,7 +331,7 @@ Before changing how a feature behaves,
 understand how websites are currently using it.
 
 Gaining a good understanding might require research,
-for example by adding metrics to a popular user agent
+for example by adding metrics to a widely-used user agent
 or by [searching the HTTP Archive](https://har.fyi/guides/getting-started/).
 Breaking content harms users,
 and the benefit of a change has to
@@ -352,7 +352,7 @@ Breakage is more likely to be acceptable if:
 * Only a tiny amount of existing content depend on the feature or behavior.
 * Only a tiny number of people see that content.
 * The content only appears in test cases or examples.
-* The content is already broken in most recent popular user agents.
+* The content is already broken in most recent widely-used user agents.
 * The content is not on the public web,
     but is instead found on internal sites
     with a controlled user environment.

From 0b0a7c1b79e975a727dfb7ebe19df27353ef87fb Mon Sep 17 00:00:00 2001
From: Jeffrey Yasskin 
Date: Fri, 19 Sep 2025 01:32:49 -0700
Subject: [PATCH 10/14] Swap "only appears"

Co-authored-by: Sarven Capadisli 
---
 index.bs | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/index.bs b/index.bs
index e53ed961..1f3910ee 100644
--- a/index.bs
+++ b/index.bs
@@ -351,7 +351,7 @@ Breakage is more likely to be acceptable if:
 
 * Only a tiny amount of existing content depend on the feature or behavior.
 * Only a tiny number of people see that content.
-* The content only appears in test cases or examples.
+* The content appears only in test cases or examples.
 * The content is already broken in most recent widely-used user agents.
 * The content is not on the public web,
     but is instead found on internal sites

From 7a7c73eb7e14841d88625e65f86fd5ea6b9e9aca Mon Sep 17 00:00:00 2001
From: Jeffrey Yasskin 
Date: Fri, 19 Sep 2025 01:55:58 -0700
Subject: [PATCH 11/14] Shorten the hidden breakage text.

Co-authored-by: Sarven Capadisli 
---
 index.bs | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/index.bs b/index.bs
index 1f3910ee..199590c8 100644
--- a/index.bs
+++ b/index.bs
@@ -358,8 +358,8 @@ Breakage is more likely to be acceptable if:
     with a controlled user environment.
     Beware in this case that internal sites are
     often invisible to analysis tools designed for public content.
-    Getting a single complaint is often a sign
-    of a much larger amount of hidden breakage.
+    A single complaint often signals
+    a larger amount of hidden breakage.
 * The benefit of breaking content is very large.
     For example, removing old SSL and TLS versions breaks lots of content
     but prevents even more security breaches.

From 1dbe45bcbcea7440a2a8aa1d20900a3ad1996175 Mon Sep 17 00:00:00 2001
From: Jeffrey Yasskin 
Date: Fri, 19 Sep 2025 21:47:46 +0000
Subject: [PATCH 12/14] Non-public breakage seems to block removal, in
 practice.

---
 index.bs | 7 -------
 1 file changed, 7 deletions(-)

diff --git a/index.bs b/index.bs
index 199590c8..6fe73573 100644
--- a/index.bs
+++ b/index.bs
@@ -353,13 +353,6 @@ Breakage is more likely to be acceptable if:
 * Only a tiny number of people see that content.
 * The content appears only in test cases or examples.
 * The content is already broken in most recent widely-used user agents.
-* The content is not on the public web,
-    but is instead found on internal sites
-    with a controlled user environment.
-    Beware in this case that internal sites are
-    often invisible to analysis tools designed for public content.
-    A single complaint often signals
-    a larger amount of hidden breakage.
 * The benefit of breaking content is very large.
     For example, removing old SSL and TLS versions breaks lots of content
     but prevents even more security breaches.

From fdc010a1d11b9ba3dc2174fa2c5ddf6ff7238b5e Mon Sep 17 00:00:00 2001
From: Jeffrey Yasskin 
Date: Fri, 19 Sep 2025 21:50:46 +0000
Subject: [PATCH 13/14] Elaborate on how existing breakage indicates that
 changes might be acceptable.

---
 index.bs | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/index.bs b/index.bs
index 6fe73573..8bd03e86 100644
--- a/index.bs
+++ b/index.bs
@@ -352,7 +352,9 @@ Breakage is more likely to be acceptable if:
 * Only a tiny amount of existing content depend on the feature or behavior.
 * Only a tiny number of people see that content.
 * The content appears only in test cases or examples.
-* The content is already broken in most recent widely-used user agents.
+* The content is already broken in some widely-used user agents,
+    and either they have not received many bug reports about it,
+    or the change is expected to improve interoperability.
 * The benefit of breaking content is very large.
     For example, removing old SSL and TLS versions breaks lots of content
     but prevents even more security breaches.

From 219c3fa03e5fdf0a8c41b625cd229ec118222c94 Mon Sep 17 00:00:00 2001
From: Jeffrey Yasskin 
Date: Fri, 19 Sep 2025 21:54:08 +0000
Subject: [PATCH 14/14] Remove local biblio now that it's in specref.

---
 index.bs | 18 ------------------
 1 file changed, 18 deletions(-)

diff --git a/index.bs b/index.bs
index 8bd03e86..e553b18b 100644
--- a/index.bs
+++ b/index.bs
@@ -24,24 +24,6 @@ Required IDs: using-http
 
 Link Defaults: html (dfn) queue a task/in parallel/reflect
-
-{
-  "the-web-is-unversioned": {
-    "authors": [
-      "Sangwhan Moon",
-      "Amy Guy"
-    ],
-    "href": "https://www.w3.org/2001/tag/doc/the-web-is-unversioned/",
-    "title": "The web is unversioned",
-    "status": "TAG Finding",
-    "publisher": "W3C",
-    "date": "27 March 2025",
-    "deliveredBy": [
-      "https://www.w3.org/groups/other/tag/"
-    ]
-  }
-}
-
 spec:css-cascade-5; type:dfn; text:inherit
 spec:css2; type: property; text: line-height