Skip to content

Rewrite the "removing features" section, incorporating "Support Existing Content" from the HTTP Design Principles #588

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 14 commits into
base: main
Choose a base branch
from
+32 −15
Open

Rewrite the "removing features" section, incorporating "Support Existing Content" from the HTTP Design Principles #588

Changes from all commits
Commits
Show all changes
14 commits
Select commit Hold shift + click to select a range
642f926
Rewrite the "removing features" section, incorporating "Support Exist…
jyasskin Sep 18, 2025
72c6e6d
Fix indentation.
jyasskin Sep 18, 2025
ec1d5a8
Apply changes from discussion
jyasskin Sep 18, 2025
bca8b85
Say who breakage harms.
jyasskin Sep 18, 2025
393f52c
Cite the-web-is-unversioned.
jyasskin Sep 18, 2025
d575739
Make the first paragraph a single sentence.
jyasskin Sep 18, 2025
f586eb5
s/help/improve experience/
jyasskin Sep 18, 2025
a61393c
s/currently/already/
jyasskin Sep 18, 2025
5b2ffa8
s/popular/widely-used/
jyasskin Sep 18, 2025
0b0a7c1
Swap "only appears"
jyasskin Sep 19, 2025
7a7c73e
Shorten the hidden breakage text.
jyasskin Sep 19, 2025
1dbe45b
Non-public breakage seems to block removal, in practice.
jyasskin Sep 19, 2025
fdc010a
Elaborate on how existing breakage indicates that changes might be ac…
jyasskin Sep 19, 2025
219c3fa
Remove local biblio now that it's in specref.
jyasskin Sep 19, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
47 changes: 32 additions & 15 deletions index.bs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -307,22 +307,39 @@ it might still be possible; see [[#removing-features]].

Do not assume that a change or removal is impossible without first checking.

<h3 id=removing-features>Remove or change capabilities only once you understand existing usage</h3>

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.
<h3 id=removing-features>Prioritize compatibility when changing or removing features</h3>

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 widely-used user agent
or by [searching the HTTP Archive](https://har.fyi/guides/getting-started/).
Breaking content harms users,
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Re @martinthomson's comment, I think we might have a higher-level principle that "The web is stable", which can cover both keeping backward compatibility and ensuring some forward compatibility. I'm inclined to try to merge this change, and then add that one, but I could reverse it if folks prefer.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think you're fine to commit this first.

and the benefit of a change has to
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
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 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.
* Only a tiny number of people see that content.
* The content appears only in test cases or examples.
* 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
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
For example, removing old SSL and TLS versions breaks lots of content
For example, removing old SSL and TLS versions breaks significant content

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

"Significant" invites a value judgement of how important the content is, while I was just trying to talk about the amount. We could use "many pages", I guess? But it's also an intentional choice to be somewhat informal here: we're trying to communicate, not impress people.

but prevents even more security breaches.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is 'even more' really needed here?

Suggested change
but prevents even more security breaches.
but prevents security breaches.

Or perhaps

Suggested change
but prevents even more security breaches.
but prevents emerging security breaches.

(or something similar)?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@matatk , "even more" could be dropped but it seems to match with "lots of" (or "significant"). Not sure if "far more" sounds better but here it is:

Suggested change
but prevents even more security breaches.
but prevents far more security breaches.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think it's important that we compare the amount of breakage with the amount of benefit. "emerging" doesn't really do that. "far more", on the other hand, might set the bar too high. I'm not actually sure that we need more instances of benefit than instances of harm, if the severities of the instances compare well, but this is just inside the SSL example, where I think it does prevent quantitatively more potential attacks. @martinthomson would know the details there. We could also pick a different example; this one was just on my mind since Martin had mentioned it recently.

The following would be fine with me, if other people prefer it:

Suggested change
but prevents even more security breaches.
but prevents more security breaches.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

+1 for "even more" or "more"


<h3 id="leave-the-web-better">Leave the web better than you found it</h3>

Expand Down