Link anchor permanence in specs

[mnot]

Hi WHATWG,

It'd be super-helpful if WHATWG had some policy about the permanence of anchors for links in its specifications; this would make it easier for other organisations to reference specific parts of WHATWG specs without fearing that the anchor will disappear.

[annevk]

In general this is the policy, but I wonder how to account for refactoring. Certain definitions have moved across specifications.

[foolip]

What is the solution in other SDOs? I suspect it is to just leave frozen versions of specs around forever? If so, we can just commit to not breaking URLs like https://dom.spec.whatwg.org/commit-snapshots/618e1f2a076fb96cef407445dac9b8c1d1301531/#interface-customevent

[domenic]

We could also make more explicit some of the things we already do, like keeping old anchors when renaming concepts.

[mnot]

I was thinking a policy along the lines of:

• if necessary, have a prefix for anchors that indicate that they're stable
• reuse old stable anchors whenever possible (including section renames)
• when a stable anchor is retired (e.g., because it's moved to another doc), add an appendix with that anchor explaining where it went / what happened
• documenting this somewhere so that people know that they can rely on it

[mnot]

@foolip everything I've heard from whatwg folks is that there's a strong preference NOT to reference the commit snapshots.

[domenic]

I've been turning this around in the back of my mind and I think I hit on the missing ingredient: communication.

That is, I'd prefer not to make a promise that every anchor in every spec will stick around forever. That hurts refactoring, removing bad ideas that didn't pan out, changing editorial things that might be linkable (such as examples), etc.

But, if I knew for a fact that some other spec was referring to a given anchor, I would go out of my way to never break that. Someone just needs to tell me!

So what about a policy where a standards organization (or anyone?) can post an issue stating that they are using a given anchor, and would the editor please make sure it sticks around forever?

This would also give a nice communication channel. First, in the near term: if someone files such an issue, the editor could let the requester know if they were actually planning on changing/removing that section soon, and begin a dialogue about how this dependency relationship might need to be rethought. And in the long term, where the editor can reach out to the original poster and let them know about changes, so they can edit their spec or issue errata or similar. (The idea being, that even if the WHATWG editor ensures incoming links work forever, the editor of the dependent spec might want to update their stuff to align with the new spec. E.g. if an algorithm changed name, even though we'd preserve the old anchor, maybe the dependent spec wants to use the new name going forward.)

Lots of potential details to be thought out. E.g., what should the bar for such a request be? (Preferably somewhat high, but also welcoming...) How can we use our tooling to enforce that these requested-to-be-stable-IDs are never lost? Etc. But I like this general idea. WDYT, @mnot?

[mnot]

Makes sense to me. I could see a process where:

• Stds org (or someone else?) files a new issue "request for permanent anchor"
• After discussion / whatever you need, it gets promoted
• That gets stored somewhere so it doesn't get lost (special anchor name? Other in-doc metadata? In-doc seems best)
• All of this gets written down somewhere so you can point people at it.

[annevk]

I think we should store them in a side-resource and then have the specification build-script ensure the anchors listed can actually be found in the generated copy of the standard and fail if that's not the case. I might even want to use something like that pro-actively (which maybe means we should distinguish between got a request for the anchor and added pro-actively) since I forgot side effects of renaming things at times.

[domenic]

I think in-document and checked by Bikeshed would be ideal. (As a slight tangent: for specs that reference us that are in the Bikeshed database, it'd be good to find all references to an anchor.)

Regardless, having something written up in the working mode seems worth working on soon, so @mnot can get back to the folks he is presumably liason-ing for with the good news :)

[domenic]

I raised whatwg/sg#72 with a first draft of such a policy. Would love thoughts from both any editors (I pinged them all there) and from folks like @mnot.

[mnot]

LGTM. I've pointed a few people at it, but that seems sufficient to me. Thanks!

[domfarolino]

I was going to comment on the PR itself, but thought it might be fitting to bring this up here:

To help an editor find the original issue thread (opened by someone wanting to reference an anchor), if it is either closed or buried somewhere, how do you feel about introducing a new label for LABELS.md called "anchor-permanence" or something to that effect? Since the PR refers to issues that are specifically open for anchor permanence and may need referred to way later on, this may be a good way to weed them out.

[domenic]

+1, we should do that. Not sure we need to write it up in the working mode or if LABELS.md suffices.

[domfarolino]

Probably just LABELS.md is my guess. I'm thinking a good chunk of people requesting a permanent anchor will not the proper access to apply a label themselves, so the editors (that already familiar with LABELS.md) will need to do it.

[domenic]

This is now done! https://whatwg.org/working-mode#anchors

[mnot]

Thanks so much!