[Openid-specs-mobile-profile] Proposed schedule for Implementer's Draft vote - version numbers

Manger, James James.H.Manger at team.telstra.com
Mon Mar 6 23:56:20 UTC 2017


Making spec titles, protocol versioning, draft numbering, and URLs more consistent at http://openid.net/developers/specs/ would be great.

But the suggested scheme would mean the HEART OAuth 2.0 Profile will be called:
  “Health Relationship Trust Profile for OAuth 2.0 1.0”
Surely that is too confusing.

The W3C does a great job of having URLs for the latest version, this version, and the previous version of a spec right at the top of each spec, eg “Web Cryptography API<https://www.w3.org/TR/WebCryptoAPI/>”.

The IETF tools site does a decent job of having links to newer & older versions (obsoleted by & obsoletes), and each draft (along with links to show differences) all at the top of the spec, eg “Hypertext Transfer Protocol – HTTP/1.1<https://tools.ietf.org/html/rfc2616>”.

I strongly suggest any version/draft includes a link to the latest version — in the spec, at the top — not just on http://openid.net/developers/specs/.


I don’t think adding 1.0 to spec titles works well. W3C uses dates in URLs and IETF uses RFC numbers — not titles. Some major protocols benefit from widely-used version numbers (eg HTTP/1.1 & 2; OAuth 2.0; S/MIME v3), but there are usually dozens of specs related to those protocols. If each spec has its own version number in the title it would be awfully confusing (eg “Health Relationship Trust Profile for OAuth 2.0 1.0”).

The 4 MODRNA specs in question are all about OpenID Connect. Including OpenID Connect’s verion number in the titles would make sense (if it was typically referred to by version, which it isn’t), but not each document’s own version.

I’m in favour of a specific URL for each doc edition being voted on; but I think “1.0” in every title is harmful.

--
James Manger

From: Openid-specs-mobile-profile [mailto:openid-specs-mobile-profile-bounces at lists.openid.net] On Behalf Of Mike Jones
Sent: Tuesday, 7 March 2017 6:41 AM
To: Bjorn Hjelm <Bjorn.Hjelm at VerizonWireless.com>
Cc: openid-specs-mobile-profile at lists.openid.net
Subject: Re: [Openid-specs-mobile-profile] Proposed schedule for Implementer's Draft vote - version numbers

One more set of questions about the specs, aimed at consistency both with the other OpenID Connect specs and internal consistency within the MODRNA specs.  First, despite James’s comments about the spec version number, it’s common practice for the specs posted at openid.net/specs/ to include a version number as a stable identifier for a particular spec version.  Thus, I plan to include the version numbers for the point-in-time specs, as well as posting them without version numbers.  The one without a version number will change over time as new versions are posted.

Second, all the MODRNA specs except for account porting include “1.0” in the spec title, which is common practice for OpenID specs (even those pre-dating OpenID Connect!).  Unless the working group objects, for consistency reasons, I plan to add “1.0” to the account porting spec title and pathname.

In summary, these are the pathnames I plan to use for the specifications unless I hear objections:
              openid-connect-modrna-authentication-1_0-06.html (stable version)
              openid-connect-modrna-authentication-1_0.html (current version)
              openid-connect-account-porting-1_0-07.html (stable version)
              openid-connect-account-porting-1_0.html (current version)
              openid-connect-user-questioning-api-1_0-10.html (stable version)
              openid-connect-user-questioning-api-1_0.html (current version)
              openid-connect-modrna-client-initiated-backchannel-authentication-1_0-03.html (stable version)
              openid-connect-modrna-client-initiated-backchannel-authentication-1_0.html (current version)

I will proceed on this basis after an ack from the chair and/or spec authors and start the 45-day Implementer’s Draft review period.

                                                       Thanks,
                                                       -- Mike (writing as OpenID Foundation secretary)

From: Manger, James [mailto:James.H.Manger at team.telstra.com]
Sent: Sunday, March 5, 2017 4:19 PM
To: Mike Jones <Michael.Jones at microsoft.com<mailto:Michael.Jones at microsoft.com>>
Cc: openid-specs-mobile-profile at lists.openid.net<mailto:openid-specs-mobile-profile at lists.openid.net>
Subject: RE: [Openid-specs-mobile-profile] Proposed schedule for Implementer's Draft vote - version numbers

draft-account-porting → openid-connect-account-porting is ok. I guess we should make this change in the repo as well.

But adding -06 to the file name is a poor idea.
“-06” is really only an approximate internal-to-working-group hint about when it is worth reviewing a draft again. We deliberately removed -0x from file names in the Bitbucket repo. It prevented having links that pointed to the latest draft (which is what you almost always want). It caused mismatches with repo commits (which already provides a separate versioning scheme).

All the current Final Specs and Implementer’s Drafts and some of the Drafts at http://openid.net/developers/specs/ have “-1_0” in their file name. Some have “1.0” in their title, but not all. Fewer have “1.0” in the label that links to the spec. This is a spec version, not a draft number. The Drafts are a mixed bag: some mention a 1.0 version, a couple mention draft numbers.

My personal preference is to omit a “1.0” version number. If there is ever an alternative approach that can introduce “v2” in its title.

For the account porting spec, I would suggest:
  Label (on web pages listing specs): “OpenID Connect Account Porting”
  Title (in spec): “OpenID Connect Account Porting — draft 06”
  File: openid-connect-account-porting.html
Plus a link to the Bitbucket repo if you want the full history, diffs etc.

I wonder if repo tags would be helpful in marking revisions that we want to remember (eg proposed & approved implementer’s draft, final spec, and spec with errata)?

--
James Manger

From: Mike Jones [mailto:Michael.Jones at microsoft.com]
Sent: Saturday, 4 March 2017 6:43 AM
To: Manger, James <James.H.Manger at team.telstra.com<mailto:James.H.Manger at team.telstra.com>>
Cc: openid-specs-mobile-profile at lists.openid.net<mailto:openid-specs-mobile-profile at lists.openid.net>
Subject: RE: [Openid-specs-mobile-profile] Proposed schedule for Implementer's Draft vote

Got ‘em – thanks.  The one thing I will do to avoid future naming conflicts is rename all the pathname occurrences of “draft-account-porting” to “draft-account-porting-06” before posting.  I realize that this means that I’ll have to edit the path to the .png file in the document.

                                                                -- Mike

From: Manger, James [mailto:James.H.Manger at team.telstra.com]
Sent: Friday, March 3, 2017 3:44 AM
To: Mike Jones <Michael.Jones at microsoft.com<mailto:Michael.Jones at microsoft.com>>
Cc: openid-specs-mobile-profile at lists.openid.net<mailto:openid-specs-mobile-profile at lists.openid.net>
Subject: RE: [Openid-specs-mobile-profile] Proposed schedule for Implementer's Draft vote

Hi Mike,

The Implementer’s Draft version of OpenID Connect Account Porting.

In repo:
https://bitbucket.org/openid/mobile/src/a5de40ec3b19227b002846a1d5d8ca5581b5c917/draft-account-porting.xml
https://bitbucket.org/openid/mobile/src/a5de40ec3b19227b002846a1d5d8ca5581b5c917/draft-account-porting.html
https://bitbucket.org/openid/mobile/src/a5de40ec3b19227b002846a1d5d8ca5581b5c917/draft-account-porting.eg.png

The draft has a *.png image in an appendix. I’m not sure how (or if) this works with the process.

--
James Manger
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openid.net/pipermail/openid-specs-mobile-profile/attachments/20170306/96d27a51/attachment-0001.html>


More information about the Openid-specs-mobile-profile mailing list