OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.

 


Help: OASIS Mailing Lists Help | MarkMail Help

chairs message

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]


Subject: RE: EXT :Re: [chairs] Re: Document numbering


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

 

From: Considine, Toby [mailto:Toby.Considine@unc.edu]
Sent: Monday, October 5, 2020 2:31 PM
To: Bret Jordan <bret.jordan@broadcom.com>
Cc: Ericson, George <George.Ericson@dell.com>; Stefan Hagen <stefan@dilettant.eu>; 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; Guy Martin <guy.martin@oasis-open.org>
Subject: EXT :Re: [chairs] Re: Document numbering

 

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.

 

tc

 

 

 

 


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. 

 

Thanks,

Bret

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."

 

 

On Mon, Oct 5, 2020 at 11:37 AM Considine, Toby <Toby.Considine@unc.edu> wrote:

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. 

 

Thanks,

Bret

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."

 

 

On Mon, Oct 5, 2020 at 10:51 AM Ericson, George <George.Ericson@dell.com> wrote:

In other groups we have done something like this:

 

  1. There is a distinction between a release number and a document version.
  2. A release number is m.n.p where:
    1. m is a major release.
    2. n is a minor release.  No backwards incompatible changes are allowed within the same major release, with exception of corrections.
    3. 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.
  1. The document version number is incremented automatically by Higher Logic on upload.
  2. Documents are self-defining:  Each document carries its revision number and its status, like 'draft', 'for approval', 'approved'.
  3. 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

 

George

 

 

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


 

Thanks,

Bret

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."

 

 

On Mon, Oct 5, 2020 at 9:51 AM Bret Jordan <bret.jordan@broadcom.com> wrote:

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)

WD 01

WD 02

WD 03

CSD 01

WD 04

WD 05

CSD 02

CSPRD 01

WD 06

CSD 03

WD 07

CSD 04

CSPRD 02

CS 01

WD 08

CSD 05

CSPRD 03

CS 02

 

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 00.1

CSD 00.2

CSD 00.3

CSD 01.0 (approved release)

CSD 01.1 (should this minor version restart or should it continue like the WDs did)

CSD 01.2

CSD 02.0 (approved release)

CSD 02.1

CSD 03.0 (approved release)

CSPRD of CSD 03.0

CSD 03.1

CSD 04.0 (approved release)

CSPRD of CSD 04.0

CS 01

CSD 04.01

CSD 05.0

CSPRD of CSD 05.0

CS 02

 

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.0.1

CSD 0.0.2

CSD 0.0.3

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.1.2

CSD 0.2.0 (approved release)

CSPRD of CSD 0.2.0

CSD 0.2.1

CSD 0.3.0 (approved release)

CSPRD of CSD 0.3.0

CSD 0.3.1

CSD 0.4.0 (approved release)

CSPRD of CSD 0.4.0

CS 1.0.0

CSD 1.0.1

CSD 1.1.0 (approved release)

CSPRD of CSD 1.1.0

CS 2.0.0

 

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. 

 

CSD 0.1

CSD 0.2

CSD 0.3

CSD 0.4

CSPRD of CSD 0.4

CSD 0.5

CSPRD of CSD 0.5.0

CSD 0.6

CSPRD of CSD 0.6

CS 1.0

CSD 1.1

CSPRD of CSD 1.1

CS 2.0

 

Obviously this is SO much easier and cleaner. 

 

Thanks,

Bret

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."



[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]