- changed status to open
URL for errata
Issue #978
open
We should get new URIs for erratas instead of over-writing the previous ones. e.g., http://openid.net/specs/openid-connect-core-1_0e1.html instead of http://openid.net/specs/openid-connect-core-1_0.html.
http://openid.net/specs/openid-connect-core-1_0.html then should be marked as "has errata" which links to the errata incorporated version.
Comments (10)
-
reporter
-
- changed milestone to Errata
- changed component to All
-
assigned issue to
Michael Jones
We already use separate URLs for each final and errata spec version and they are never overwritten. For instance, for Core, these URLs are, respectively, http://openid.net/specs/openid-connect-core-1_0-final.html and http://openid.net/specs/openid-connect-core-1_0-errata1.html.
We also have a URL for the current version, in this case, http://openid.net/specs/openid-connect-core-1_0.html. It currently contains a copy of -errata1.
The new errata, once approved, will be released at http://openid.net/specs/openid-connect-core-1_0-errata2.html and http://openid.net/specs/openid-connect-core-1_0.html. References should continue to use the current version URL.
-
We should probably make a blog post saying how other specs can reference current versions and specific versions, as makes sense in their use cases.
-
reporter
There should be [errata exists] and [errata incorporated on] on the each side so that the readers can refer to each other.
-
I strongly believe that we must not edit existing approved specifications in any way. That's an important part of our contract as a standards organization to users of the standards. In particular, this precludes editing "Final OpenID Connect Core 1.0" and "Final OpenID Connect Core 1.0 incorporating errata set 1" to add anything.
I'm fine adding links to these previous versions when we create "Final OpenID Connect Core 1.0 incorporating errata set 2" to help people locate the previous versions, should they want to do so - and likewise for the other specs we're creating new errata versions for.
-
As discussed during the 17-Jun-21 call, we already indicating the presence of errata by including “incorporating errata set N” in the titles of updated documents. We do update the unversioned URLs, which point to the most current approved drafts, such as https://openid.net/specs/openid-connect-core-1_0.html. Since the unversioned URLs are the ones actually referenced, including by search engines, we are already accomplishing the goal of this issue. I therefore propose that we close this issue on that basis.
-
Will be fixed by https://bitbucket.org/openid/connect/pull-requests/568
-
I strongly believe that we must not edit existing approved specifications in any way. That's an important part of our contract as a standards organization to users of the standards. In particular, this precludes editing "Final OpenID Connect Core 1.0" and "Final OpenID Connect Core 1.0 incorporating errata set 1" to add anything.
I mostly agree with this stand point, but I think there is precedent for small changes to indicate that a specification is no longer the current version - for example, IETF RFCs can be I believe be marked “Obsoleted by” and “Errata exist”. I believe making a small change (similar to what Nat suggested) would be highly beneficial to readers of the specification that may not realise they have unintentionally ended up on an older version of the specification.
-
I don’t believe that I have authority to edit published specifications. If we want to edit published versions, I wouldn’t be comfortable doing so without a board resolution directing me to do so.
I do have authority to reference past versions in new ones to be published, as I’ve done in https://bitbucket.org/openid/connect/pull-requests/568. I did change “Fixes #978” to “In at least partial satisfaction of #978“ in the PR so merging the PR won’t close the issue. I hope you can now approve PR #568 on that basis, since it makes things better.
-
Thanks Mike! I approved that, and agree it makes things better. I also agree that getting a wider consensus before editing published versions is a good thing to do.
- Log in to comment
WG call on Aug 17 agreed that since other specs may be referencing it, it is better not to over-write the content of a URI unless it is purely editorial.