Update EIP-1: add support for linking to other well known SDO specifications #6691
Conversation
This defines how EIP authors can link to RFCs, W3C specs, and WHATWG specs. It additionally defines regexes that comply with the stable links that are used by each SDO so that the eipw bot can be updated easily as well.
File
|
There was a problem hiding this comment.
+1 to RFC
? to W3C. I can't find any rules about finality. +1 if it has well-defined rules regarding updates and errata.
-1 to unconditionally allowing linking to WHATWG. +1 to linking to specific versions of WHATWG specs (e.g. https://console.spec.whatwg.org/commit-snapshots/1bf0d64c1bb91e1b333b7494470f5d6c7c30fd3e/), and +1 to linking to linking to immutable portions of WHATWG specs (if applicable).
|
Errata management is defined here for W3C: https://www.w3.org/2021/Process-20211102/#errata, something to note is that substantive changes require full process to Revise a recommendation. In practice, this usually just means things get kept to minimal editorial updates to fix spelling issues and minor notes because it's not normal for WGs to stay chartered for managing these. Versions of specifications do have stable URLs which are in TR namespace such as https://www.w3.org/TR/vc-data-model/ however these can be updated a bit. E.g. That link redirected from v1.0 to v1.1 once the WG completed a set of proposed changes which were editorial. Our WG didn't allow us to make substantive changes which is why v2.0 has been started. With that said, I think what you'd actually be interested in is the date stamped URLs which don't change. The example of this is https://www.w3.org/TR/2022/REC-vc-data-model-20220303/ which won't change. That date is reflective of the date it was published which would make it the same as what's published at https://www.w3.org/TR/vc-data-model/. Another thing to note is candidate recommendation and working drafts can be published in the TR namespace, which I don't believe we should be linking to. These are effectively the same as in progress EIPs or versions of an internet draft in IETF. So with all that in mind, I think what you'd be supportive of @Pandapip1 is date locked Recommendation specs in TR namespace since that would never be changed or removed. |
|
Also, now that I think about it. If we only want to reference stable content we should not be allowing referencing EIPs which are anything but "Final" status. Otherwise, the content can be changed which runs into the same problem as we'd have with referencing a standard at a different SDO that allows errata. This would be the consistent way to apply this principle of never referencing in progress specifications. |
Final can only link to Final, Last Call to Last Call and Final, and so on. See |
|
Ok, I didn't realize that was how the bot was working so thanks for linking to it. It seems plausible that EIPs will move in progress together, but references to external specs I'm definitely of the opinion linking to final is better. The one scenario where this might cause an issue is when someone for example is working on a cryptography related EIP for something like core and want to link out to a CFRG draft. An example where this might have occurred is the BLS signatures EIP may have wanted to reference pairing-friendly-curves draft. Do we want to allow that now? I'm of the mindset we can just update the exceptions list easily if we come across that specific case in the future, so fine to say no to that for now. |
That's my thought too. |
Co-authored-by: Gavin John <[email protected]>
kdenhartog
changed the title
@kdenhartog I think you just forgot to merge this
|
The commit c39b9ff (as a parent of bbddc90) contains errors. |
|
The case can be made for Unicode, IANA, ISO, and ITU that covers almost all: https://en.wikipedia.org/wiki/Web_standards I can see wanting to link to specs from those published organizations potentially. |
Please submit PRs for these individually. ISO in particular would be controversial as the specs are paid (and as such, I am strongly against allowing ISO specs) |
|
@sambacha I typically agree, but don't want to expand the scope of this PR since there's generally reasonable consensus around these 3 at this point since I've been discussing these ones with the editors since I wanted to link to them in 5593. |
| ### Other Well Known Standards Bodies | ||
|
|
||
| Links to other well known standards bodies specification may be included using normal markdown syntax. Be mindful of the requirements set for each SDO as these were chosen in order to maintain links to stable URLs. | ||
|
|
There was a problem hiding this comment.
| ### Other Well Known Standards Bodies | |
| Links to other well known standards bodies specification may be included using normal markdown syntax. Be mindful of the requirements set for each SDO as these were chosen in order to maintain links to stable URLs. |
|
|
||
| Links to other well known standards bodies specification may be included using normal markdown syntax. Be mindful of the requirements set for each SDO as these were chosen in order to maintain links to stable URLs. | ||
|
|
||
| #### World Wide Web Consortium (W3C) |
There was a problem hiding this comment.
| #### World Wide Web Consortium (W3C) | |
| ### World Wide Web Consortium (W3C) |
| Links to a W3C "Recommendation" status specification may be included using normal markdown syntax, where the content of the link is the title of the specification. For example, the following link would be allowed: | ||
|
|
||
| ```markdown | ||
| [W3C Secure Context](https://www.w3.org/TR/secure-contexts/) |
There was a problem hiding this comment.
EIP-5757 says that origins must "provide a method of uniquely identifying a particular revision of a resource". To that end, I'd recommend that we use "this version" links and not the latest version links.
Also, the title of that standard is "Secure Contexts", not "W3C Secure Contexts" as far as I could tell?
How about this for the example:
| [W3C Secure Context](https://www.w3.org/TR/secure-contexts/) | |
| [Secure Contexts](https://www.w3.org/TR/2021/CRD-secure-contexts-20210918/) |
|
|
||
| Which renders as: | ||
|
|
||
| [W3C Secure Context](https://www.w3.org/TR/secure-contexts/) |
There was a problem hiding this comment.
| [W3C Secure Context](https://www.w3.org/TR/secure-contexts/) | |
| [Secure Contexts](https://www.w3.org/TR/2021/CRD-secure-contexts-20210918/) |
| Permitted W3C recommendation URLs MUST anchor to a specification in the technical reports namespace, and so MUST match this regular expression: | ||
|
|
||
| ```regex | ||
| ^https:\/\/www.w3.org\/TR\/.*$ |
There was a problem hiding this comment.
| ^https:\/\/www.w3.org\/TR\/.*$ | |
| ^https:\/\/www.w3.org\/TR\/[0-9][0-9][0-9][0-9]/.*$ |
|
|
||
| [RFC 8446](https://www.rfc-editor.org/rfc/rfc8446) | ||
|
|
||
| Permitted IETF specification URLs MUST anchor to a specification with an assigned RFC number (meaning cannot reference internet drafts), and so MUST match this regular expression: |
There was a problem hiding this comment.
Do we want to allow links to proposed standards?
| Links to WHATWG specifications may be included using normal markdown syntax, where the content of the link is the title of the specification, followed by ` Specification` if applicable. For example, the following link would be allowed: | ||
|
|
||
| ```markdown | ||
| [WHATWG HTML Spec](https://html.spec.whatwg.org/) |
There was a problem hiding this comment.
This ends with "Spec" while the text above says "Specification".
| Links to WHATWG specifications may be included using normal markdown syntax, where the content of the link is the title of the specification, followed by ` Specification` if applicable. For example, the following link would be allowed: | ||
|
|
||
| ```markdown | ||
| [WHATWG HTML Spec](https://html.spec.whatwg.org/) |
There was a problem hiding this comment.
We prefer links to exact versions:
| [WHATWG HTML Spec](https://html.spec.whatwg.org/) | |
| [WHATWG HTML Spec](https://html.spec.whatwg.org/commit-snapshots/578def68a9735a1e36610a6789245ddfc13d24e0/) |
With the commit, the reader is aware of exactly where the living standard was when the EIP was finalized. The reader can then choose exactly how to implement the EIP: either as written, or with the latest spec from WHATWG.
|
|
||
| Which renders as: | ||
|
|
||
| [WHATWG HTML Spec](https://html.spec.whatwg.org/) |
There was a problem hiding this comment.
| [WHATWG HTML Spec](https://html.spec.whatwg.org/) | |
| [WHATWG HTML Spec](https://html.spec.whatwg.org/commit-snapshots/578def68a9735a1e36610a6789245ddfc13d24e0/) |
| Permitted WHATWG specification URLs MUST anchor to a specification defined in the spec subdomain (idea specifications are not allowed), and so MUST match this regular expression: | ||
|
|
||
| ```regex | ||
| ^https:\/\/[a-z]*.spec.whatwg.org.*$ |
There was a problem hiding this comment.
| ^https:\/\/[a-z]*.spec.whatwg.org.*$ | |
| ^https:\/\/[a-z]*.spec.whatwg.org/commit-snapshots/[0-9a-f]{40}/$ |
|
Going to repurpose this one to be focused just on WHATWG to align with @SamWilsn new PRs that split out IETF and W3C |
|
No need to apologize, thank you for taking this over to make sure it got closed out! |
This defines how EIP authors can link to RFCs, W3C specs, and WHATWG specs. It additionally defines regexes that comply with the stable links that are used by each SDO so that the eipw bot can be updated easily as well.