GitHub Branches and Releases

[davaya]

We discussed GitHub release management at the Feb 2 TC working meeting.

Should the GitHub Published branch include CSDs?

The Kavi TC page has folders for

• Approved Work Products (CS, CSD, and OASIS Standards) published by OASIS Staff
• Working Drafts published by TC members (TC Secretary or document editors)

The OASIS public Standards page lists CS and OS documents but not CSDs.

Reasonable arguments can be made for both approaches - CSDs published by OASIS are "published" and belong in the Published branch, or CSDs published by OASIS are still Drafts and belong in the Working branch. Depending on the day of the week I could prefer either approach. Yesterday I liked CSD + CS so users get the latest OASIS docs when they look at the default branch. Today I like the current CS-only approach so users see the latest "stable official" version by default. Naming the default branch "published" may be part of the problem; it might more clearly represent CS-only if it were called "stable", or even just "main".

Should GitHub include final versions edited for publication by OASIS staff?

In my opinion, yes. The CS or CSD documents we submit to OASIS for publication are still working documents even if we remove WDxx from the name before submitting. Only documents edited by OASIS are "official". We should discuss with Chet/Paul whether they should remove the WDxx as part of their publication process, since anything created by the TC and committed to GitHub is by definition a WD.

How should working versions be numbered

In my opinion, once OASIS publishes a document as "Version 1.0 CS01" we should immediately commit it to GitHub as the baseline for the next version "Version 1.1 CSD01 WD00". "Version 1.1 CSD01 WD01" would then be our first commit towards that next version. If we found non-material changes / errata, we would commit them as "Version 1.0 CS02 WD01" (or "Version 1.0.1 WD01" if OASIS chooses to replace CS numbers with SemVer).

Should OASIS adopt Semantic Versioning?

We should discuss with Chet/Paul whether OASIS might adopt SemVer numbering so there is never a Version 1.0 CS02. A document with only non-material changes from a Major.Minor version would be published as a Major.Minor.Patch number (Version 1.0.1) with no CS number. That would certainly make the Standards page easier to read, since only Version numbers are visible, not CS numbers.

[dlemire60]

Questions were submitted to OASIS TC Ops regarding this; still awaiting a reply:

We had some process-oriented discussion in our working meeting today that led to questions I’d like your opinion on. As we’ve documented in our TC’s Documentation Norms [github.com], in our GH repos:

1. The Published (default) branch contains Committee Specification and higher versions of the work product published by OASIS (AKA “OASIS Standards Final Deliverables [oasis-open.org]”, per the defined terms)
2. The Working branch contains the on-going, under-development version of the work product
3. Working drafts and CSDs are documented using the GH release mechanism (the latter part of that, tagging CSDs as releases, was part of today’s discussion and I have an action to document that more clearly)

Technically, CSDs are also published by OASIS (at least, that’s the label on the TCADMIN ticket I submit ). But we think the distinction between draft and final deliverables is relevant when someone visits a repo to learn about the work product. The point was made in this morning’s discussion that in Kavi CSDs appear in TC document stores in the Approved Work Products folder along with CSes, which might argue that we should also put CSDs into our Published branch, to align with the way Kavi is used.

So my question are:

1. Do you have any disagreement with our approach in any of items 1, 2, or 3 above?
2. Do you think we need to make any modifications to better align with OASIS working precedent?

[dlemire60]

In my opinion, once OASIS publishes a document as "Version 1.0 CS01" we should immediately commit it to GitHub as the baseline for the next version "Version 1.1 CSD01 WD00". "Version 1.1 CSD01 WD01" would then be our first commit towards that next version.

I have a quibble with this: the next version is a long way from a CSD at this point, so the tag should not include any reference to CSD. The new label should instead be "Version 1.1 WD00"; I'd also use the GH Release feature to tag that as a clear point-in-time version (although in this case I believe there's no need to download the release and upload it back to Kavi as "v1.1 wd00"), especially as for many specs there may never be a v1.1.

I do think it's very important that front matter updates and document content tweaks done by OASIS TCADMIN need to be captured back into the working version promptly, even for CSD level publication, simply to save them the effort of performing the same tweaks / fixes multiple times. These items are usually itemized in a publication email to the TC from TCADMIN.

[davaya]

WDs and CSDs are both draft designators preceding the Version to be released. So if v1.0 CS01 is published, the drafts leading up to the next version would be (hypothetically):

• V1.1 virtual WD00 (=V1.0 CS01)
• V1.1 WD01
• V1.1 WD02 (submitted to OASIS for V1.1 CSD01)
• V1.1 WD03 (published by OASIS as CSD01)
• V1.1 WD04
• V1.1 WD05 (submitted to OASIS for v1.1 CS01)
• V1.1 CS01 published by OASIS (= virtual V1.2 WD00)

If we don't include CSD numbers for WDs, then the WDs have to be sequential from one CS to the next, which is OK with me. It just seems a little strange to have no CSD numbers for some WDs but not all. We should compare the alternatives for GitHub tags and document title page Version in a spreadsheet (I don't think issues can have tables so it's hard to compare here).

I don't think we have to actually commit a document called WD00 with that being the only change from the OASIS-published CS, we just sync the working branch to the main branch (on TC repo and all forks) and remember to change the version number when the first PR for WD01 is merged to the working branch.

[dlemire60]

I believe at least some of these questions have been resolved by PR #49

Please review the current section 4 of Documentation Norms and identify any residual concerns here.

[davaya]

The bottom of Figure 4 says "Update working from CSzz". That still leaves the file content and WD numbering unspecified. New product development begins with an OASIS-provided template, and WD01 is the first committee-developed material applied to it. After publication of a CS, development (should) begin with the CS, with the PRs that go into the next WD being based on something called either WD00 or WD01 that is just the CS with new version and WD numbers assigned.

The question of what to check out and edit immediately after a CS publication is still not fully specified (or it is but I fail to understand it).