Process to submit Committee Specification Public Review Draft - oasis-tcs/oslc-domains GitHub Wiki

Since the Domains TC is going to be managing a significant number of documents through the OASIS process, it will be helpful to summarize that process here.

OASIS Specification Lifecycle

The OASIS Specification Lifecycle consists of:

Each of these document states results in content being published in the OSLC Domains TC Approved Documents folder. The TC administrator publishes the documents in this folder after the Full or Special Majority Vote of the TC to approve the documents for publications.

Useful Links

Process to create a Committee Specification Public Review Draft

This document summarizes the process, using the OSLC Requirements Management 2.1 Specification Committee Specification Public Review Draft 01 as an example.

  • Complete any changes to the specification and update:
  • specification stage
  • revision
  • this, previous and latest version URLs

Checkin changes to SCM if needed.

  • Use ReSpec to generate a snapshot of the final HTML document and name the result according to OASIS naming directives. Then Use Firefox with the Adobe plugin to generate the PDF files, edit the PDF files and add the required footer.

  • Prepare the oslc-rm-csprd01.zip file containing the authoritative HTML and PDF published documents - the date should be on or about the date the documents were published. Since this will require a Full Majority Vote, the date will need to be the exact date that the approval ballot closes. We can coordinate that in advance with the TC Administrator.

  • Send the oslc-rm-csprd01.zip file to OASIS TC Administrator (Chet and/or Paul) to get feedback

This is not strictly necessary but certainly no problem checking with OASIS. If any of the front page metadata needs adjusting during publication, OASIS can work on that with you at that stage.

Now that ReSpec more closely creates final publishable HTML, there are less changes from OASIS. However, their feedback is generally thorough and valuable.

  • Apply any required updates and recreate the updated oslc-rm-csprd01.zip file, this is the content that will be published

  • Checkin all changes necessary to create the oslc-rm-csprd01.zip file and tag the resources in SCM to preserve a baseline of the published resources. This is useful to automate capturing the differences between specification revisions.

  • Hold a TC Simple Majority Vote on a motion to approve CSPRD01 referencing the URL to the working draft:

I move that the TC approve OSLC Requirements Management Specification Version 2.1 and all associated artifacts packaged together in https://www.oasis-open.org/apps/org/workgroup/oslc-domains/download.php/63176/oslc-rm-csprd01.zip as a Committee Specification Draft, designate the HTML version of the document as authoritative, and for 30 days public review.

The closing date of that ballot is also the date that will be on the published spec. We should work out the timing in advance so that you don't have to go back and change the files after the vote.

  • Once the TC vote closes (if its electronic) Request a Full Majority Vote to approve a Committee Specification Draft, Public Review Draft. This requries:
  • Title and version of the CSD to be approved
  • TC mailing list: [email protected]
  • URL of comment resolution log
  • link to TC meeting minutes where the motion to approve passed (or link to approved electronic ballot)

See Request a first public review for an approved specification.

  • Once the special majority vote closes and is approved, update the dates in the oslc-rm-csprd01.zip file contents (if necessary) to be the date the special majority vote was approved.

Or coordinate the dates in advance to avoid having to change them in published documents.

  • Request that the TC Administrator Publish a Committee Specification Draft / Public Review Draft

OASIS will probably do that step for you. Typically, once OASIS TC Administrator gets the notice that the ballot closed, he will go ahead and open the Publish CS ticket on behalf of the TC. But its ok for the TC to create the request too.