|
I'm not clear what semantic versioning people keep looking for.
I just looked at my last spec that went past committee spec to oasis spec. The lines on the front page of the CS are:
Energy Interoperation Version 1.0
Committee Specification 02
[Committee Specification 01 with errata]
18 February 2012
the uri contains all the semantic info typically considered in semantic versioning
Committee/spec/major release/minor release.
The only thing left out is the working drafts. This thread started with a suggestion that it was too confusing to make working drafts.
And working drafts are just that. I have been in meetings where 3 of those were produced in the meeting (I won't vote this out unless I see paragraph 3 updated like so!)
That did turn into
Energy Interoperation Version 1.0
OASIS Standard
11 June 2014
That was in the days when it was much more difficult to get the votes for an OASIS standard.
I'm not sure what more is meant by semantic versioning in this thread. We have long had
Major/Minor/Bugfix
with backward compatibility w/i a Major
This was all defined in the Artifact Naming Rules produced by the TAB a decade ago.
Is there something more that those brining up "Semantic Naming" are looking for, an explicit goal?
tc
From: Stefan Hagen <stefan@dilettant.eu>
Sent: Tuesday, October 6, 2020 1:50 PM
To: Paul Knight <paul.knight@oasis-open.org>
Cc: Considine, Toby <Toby.Considine@unc.edu>; Lemire, Dave (HII-TSD) <david.lemire@hii-tsd.com>; Bret Jordan <bret.jordan@broadcom.com>; Ericson, George <George.Ericson@dell.com>; Chet Ensign <chet.ensign@oasis-open.org>; OASIS TAB <tab@lists.oasis-open.org>;
Martin Chapman <martin.chapman@oracle.com>; chairs@lists.oasis-open.org <chairs@lists.oasis-open.org>; Guy Martin <guy.martin@oasis-open.org>
Subject: Re: [tab] RE: EXT :Re: [chairs] Re: Document numbering
On the day of black hole physic nobel prizes winners ... it seems we gently drift in space.
I love semantics - line numbers are not a part of my prose world.
As Bret remembered - thanks for that - I would love to have some kind of semantic versioning on standards work products - if possible.
I already learned many shortcuts people in TCs take to reduce formalities in their standards production pipelines and our sometimes hamster wheels .. thank you Bret for pushing this threat - even learning about these was Beneficial for me and
hopefully others.
Many TCs seem to work in their more or less comfortable bubbles - I hoped in my first year as elected TAB member to push open office hours and the like to foster this collaborative team think across OASIS scaling better than me jumping into N
TCs to help finish stuff ...
All the best and happy githubbing our standards or gitlabbing for what it*s worth.
Stefan
Am 06.10.2020 um 19:14 schrieb Paul Knight <paul.knight@oasis-open.org>:
ï
Hi all,
Responding only to the "line numbering on PDF" discussion:
I do agree with Toby that line numbers in PDF can be useful for comments, but it is not widely requested, so I don't think it makes sense for it to be a requirement. TC Admin can add the line numbers on request during publication.
As Dave Lemire noted, line numbers are easy to add if the specification starts from Word or OpenOffice/LibreOffice.
I do not know of a "beautiful" way to do it, starting from Markdown or HTML, although I DID develop a fairly useful and functional way to do this for OpenC2. While it doesn't track the text exactly, it's certainly good enough for commenting purposes.
Of course, I'd be happy to find a tool or automated process to do this better.
Best regards,
Paul
Writage is a currently free MS Word add-in that reads and writes MD, lets you pull in any MD, add line numbers, save as PDF. Line numbers will change in Word and other formats
based upon the printer in use, so the PDF step is useful to make them immutable. I do not know any way to add line numbers in MD printed output (which is all you need to get into PDF) at this time.
The same sort of round tripping into a published artifact works quite well for Google docs.
The Fintech guys, who use MD in *their* github work recommend editing MD files in OpenOffice or LibreOffice. Both OpenOffice and LibreOffice support line numbering as
well, and each can of course print to the immutable PDFs.
A quick search suggests that adding attr.output = ".numberLines" to MD files makes them number directly when printed, but I have no experience with that.
tc
Iâll note that line numbering is easy if youâre working in a traditional word processor. Itâs much harder when youâre creating in markdown and publishing
in markdown and HTML. I guess you can refer to line numbers in the markdown text source.
Dave
David Lemire
HII Mission Driven Innovated Solutions (HII-MDIS)
Technical Solutions Division
302 Sentinel Drive | Annapolis Junction, MD 20701
Work (301) 575-5190 |
Mobile (443) 535-1182
|
|
CAUTION: This email originated from
outside your organization. Exercise caution when opening attachments or clicking links, especially from unknown senders.
|
Maybe that goes back to why I believe that the review copies of each document must include line numbers.
If you comment is that in WD047 that there is some confusion in lines 137-144, I can as editor easily find the text, easily say "Oh, we deleted two paragraphs, so that is now lines
114-121, and I can see the confusion"
As an editor I always valued all those comments, because it meant someone was at least reading it.
From: Bret Jordan
Sent: Monday, October 5, 2020 2:00 PM
To: Considine, Toby
Cc: Ericson, George; Stefan Hagen; Chet Ensign; OASIS TAB; Martin Chapman;
chairs@lists.oasis-open.org; Guy Martin
Subject: Re: [chairs] Re: Document numbering
Yeah, the conceptual high level theory is great. The wheels fall off the bus when you get into the specifics and actually have to relate which version is which. This is where things go bad really quick.
PGP Fingerprint: 63B4 FC53 680A 6B7D 1447 F2C0 74F8 ACAE 7415 0050
"Without cryptography vihv vivc ce xhrnrw, however, the only thing that can not be unscrambled is an egg."
I've been on stages talking to hundreds of people about the progress of current OASIS work, and the difference between WD and CSDs, and then entertained questions from the audience.
There never seemed to be any confusion. The most frequent reaction was to be impressed by the clarity and openness of the documents and numbers, particularly by those who had worked
in some of the other standards groups.
From: Bret Jordan
Sent: Monday, October 5, 2020 1:03 PM
To: Ericson, George; Stefan Hagen
Cc: Chet Ensign; OASIS TAB; Martin Chapman;
chairs@lists.oasis-open.org; Guy Martin
Subject: Re: [chairs] Re: Document numbering
I would be all for a consistent and easy to understand system. I know Stefan had a proposal for semantic versioning at one point. The point is we really need to fix and improve this. The fact that an outsider to OASIS can not have a
clear understanding of the status of a document is just nuts and when that outsider tries to talk to a TC member and the TC member is used to working on a Working Draft number and the outsider is talking about Version 1.0 or version 2.1 and the TC member is,
but which CS or CSD or WD number are you actually talking about.
PGP Fingerprint: 63B4 FC53 680A 6B7D 1447 F2C0 74F8 ACAE 7415 0050
"Without cryptography vihv vivc ce xhrnrw, however, the only thing that can not be unscrambled is an egg."
In other groups we have done something like this:
- There is a distinction between a release number and a document version.
- A release number is m.n.p where:
- m is a major release.
- n is a minor release. No backwards incompatible changes are allowed within the same major release, with exception of corrections.
- p is a correction to a minor release. It may introduce a backwards incompatible correction if the correction is necessary and in line with the original intent. It may not introduce new functionality.
- The document version number is incremented automatically by Higher Logic on upload.
- Documents are self-defining: Each document carries its revision number and its status, like 'draft', 'for approval', 'approved'.
- The document revision number of each document version is the intended approved revision number.
This captures the difference
|
Alternative proposal
|
Original Proposal
|
|
Version
|
Revision
|
Status
|
|
1
|
1.0.0
|
Draft
|
WD 01
|
|
2
|
1.0.0
|
Draft
|
WD 02
|
|
3
|
1.0.0
|
Draft
|
WD 03
|
|
|
|
|
CSD 01
|
|
4
|
1.0.0
|
Draft
|
WD 04
|
|
5
|
1.0.0
|
Draft
|
WD 05
|
|
|
|
|
CSD 02
|
|
6
|
1.0.0
|
For approval
|
CSPRD 01
|
|
7
|
1.0.0
|
Draft
|
WD 06
|
|
|
|
|
CSD 03
|
|
8
|
1.0.0
|
Draft
|
WD 07
|
|
|
|
|
CSD 04
|
|
9
|
1.0.0
|
For approval
|
CSPRD 02
|
|
10
|
1.0.0
|
Approved
|
CS 01
|
|
11
|
1.1.0
|
Draft
|
WD 08
|
|
|
|
|
CSD 05
|
|
12
|
1.1.0
|
For approval
|
CSPRD 03
|
|
13
|
1.1.0
|
Approved
|
CS 02
|
From: Bret Jordan <bret.jordan@broadcom.com>
Sent: Monday, October 5, 2020 12:00 PM
To: Chet Ensign; OASIS TAB; Martin Chapman;
chairs@lists.oasis-open.org
Subject: [chairs] Re: Document numbering
Oh and do not forget that the documents also have a Version number that somehow has to be correlated to a CSD / CS version as well. Honestly, the way we do document versioning is just a mess and inconsistent TC to TC. So you could have:
Version 3.1.4 = CS 02 = CSPRD = 03 = CSD 05 = WD 08
PGP Fingerprint: 63B4 FC53 680A 6B7D 1447 F2C0 74F8 ACAE 7415 0050
"Without cryptography vihv vivc ce xhrnrw, however, the only thing that can not be unscrambled is an egg."
Chet, et al.,
Please forward to the process committee.
As a board member I worked on trying to remove the working draft concept and have us just use CSDs. However, given that CSDs require some sort of formal approval to release, aka a ballot, then we still have a problem. It comes from document numbering and
being able to release documents on a routine basis.
Old System: (we understand the confusion and problems really well with this system)
So a TC only really reviews and works on working drafts. Yes, some only review CSDs, but that is not the majority of active people. So in this old model we have CS 02 = CSPRD = 03 = CSD 05 = WD 08. An utter mess.
With the new proposed model, there is no real semantic way of versioning the documents between approved releases of CSDs. So it makes it really difficult to keep track of what version you are working on. So much added complexity. About the best you can do
is something like:
CSD 01.0 (approved release)
CSD 01.1 (should this minor version restart or should it continue like the WDs did)
CSD 02.0 (approved release)
CSD 03.0 (approved release)
CSD 04.0 (approved release)
SO CS 02 = CSD 05.0. This still seems a bit confusing. Maybe we do something like the following. This would keep a consistent semantic number scheme regardless of the delivery "stage".
CSD 0.1.0 (approved release)
CSD 0.1.1 (should this minor version restart or should it continue like the WDs did)
CSD 0.2.0 (approved release)
CSPRD of CSD 0.2.0
CSD 0.3.0 (approved release)
CSD 0.4.0 (approved release)
CSD 1.1.0 (approved release)
If we could get out of the notion of having CSDs be formally approved. Maybe the TC can have a standing rule that they can be released weekly or twice a month or when the Chairs and Editors find them to be in a good state. This would give us the following.
Obviously this is SO much easier and cleaner.
PGP Fingerprint: 63B4 FC53 680A 6B7D 1447 F2C0 74F8 ACAE 7415 0050
"Without cryptography vihv vivc ce xhrnrw, however, the only thing that can not be unscrambled is an egg."
--
OASIS - Advancing open standards for the information society
|