Skip to content

EPIC checklist

Jump to bottom
Andrew Berezovskyi edited this page Oct 22, 2021 · 19 revisions

EPIC checklist

WORKING DRAFT: N/A
OASIS issue: N/A
Published spec: N/A

Preflight

  • Read the guidelines
  • Create a milestone for this stage (link)
  • Add this issue to the newly created milestone and tag it "Kind: EPIC"
  • Search for all open issues and add the relevant ones to the milestone
  • Reset the status to WD and publication date to "null". Push the changes to master and verify the draft webpage says "Working Draft ##" and does not have a date.
  • Add the WD draft link to the top ☝️ (see https://github.com/oslc-op/oslc-specs#quick-links and update the table as well if needed)

Spec text and ReSpec

  • Ensure latest ReSpec is used (link)
  • Remove Part #: from the titles of the Additional components for the vocabulary and shapes Turtle files. (ref, added 2020-09-09)
  • Make sure all URIs in the Additional components are fully qualified (ref, added 2020-09-09)
  • head section contains a meta element with name="description" and content="{same text as in the abstract}"
  • Update references to obsolete PSDs to point to the latest revisions. See https://open-services.net/specifications/ for a list of obsolete publications.
  • All issues in the milestone are resolved
  • Ensure no critical ReSpec errors (red) are present (see the ReSpec button in the top right corner)
  • specStatus set to the desired stage (PSD or higher)
  • publishDate set to the date of the PGB vote + 7 days (e.g. if you plan to open the vote on Mar 12, set it to Mar 19). Make sure to use the UTC timezone and set the time to 12:00 (why), e.g. "2021-01-01T12:00Z".
  • Every single shape resource can be navigated via its # anchor in the Constraints part.

Machine readable RDF documents

OASIS

  • Create a snapshot from the specs and ZIP em up (instructions
  • Ensure no HTML errors are present in the saved snapshot of every part of the spec (check via File Upload option of the W3C checker). An exception has been made not to fix HTML5 errors that relate to dropped HTML table attributes.
  • No broken links other than the stage-to-be-published (cf. https://github.com/oslc-op/oslc-specs/wiki/Publication-guidelines#overall-process)
  • Release Draft created (TODO add a hyperlink here to the Release Draft once created, create one here)
  • Release ZIP uploaded, TODO add a hyperlink to the Release ZIP once created)
  • Notify the PGB of the intent to publish (template, ask a PGB member if you are not on the board). The vote can be initiated at least 14 days after this letter has been sent.
  • OASIS publication request filed under oasis-open-projects/administration. New location is https://www.oasis-open.org/project-administration-support-requests/; search OASIS Jira for an automatically generated ticket. (Add the ticket link to the top ☝️)
  • PGB vote initiated (template, TODO add date)
  • PGB vote passed and Chet closed the ballot (TODO add hyperlink to the announcement email)
  • OASIS feedback addressed
  • The spec is published to the OASIS staging archive
  • OASIS review passed
  • The spec is published to the OASIS archive (Add the published link to the top ☝️)

After the publication

  • Tag the commit that was used to produce published snapshots with %shortname%-v%version%-%STAGE%%REVISION%.
  • Promote the draft (pre-)release to a (pre-)release. PSDs are pre-releases.
  • Add a new row to the https://github.com/oslc-op/website/edit/master/content/specifications/_index.md under Active publications with the link to the published spec
  • Move the old row (of the same version only) in the https://github.com/oslc-op/website/edit/master/content/specifications/_index.md from the Active publications to the Obsolete Publications table (DO NOT JUST DELETE AN OBSOLETE SPEC ROW!)
  • open-services.net redirects resolve to the current published specs/drafts (ask Andrew, info)
  • open-services.net blog announcement (spec editor prepares a blog post, see here and there, Andrew will do the deployment). The announcement will automatically appear on the forum.
  • LinkedIn announcement (Axel)
  • Twitter announcement (Andrew)

Kitchensink (ONLY FOR THE FIRST PSD!)

If this is the first PSD of the spec in the open project, there are many possible issues (accumulated from previous OASIS reviews). Please make a quick check to avoid having them and to speed up the review.

  • [ReSpec] Base URI updated to the OP archive (docs.oasis-open-projects.org and not docs.oasis-open.org unless it's for a published previous stage). Look for "var oasisBase=".
  • [ReSpec] latestVersion updated to point to the one for the OP, not the TC (only for the first PSD)
  • [ReSpec] additionalArtifacts links are relative
  • [OASIS/RM] in "Notices", the copyright year is missing - between "OASIS Open" and the period
  • [OASIS/RM] the links to the "Previous stage" should use http instead of https in this case, since the earlier files were installed with http links. When the HTML is retrieved using https, it is unable to load the associated .css file, so the document is poorly presented.
  • [OASIS/RM] add HTTPS to the image references
  • [OASIS/RM] in Vocabulary, I would expect that the first two definition should be placed under 2.1.1, since they are Classes rather than Properties. See https://github.com/oasis-tcs/tab-respec/issues/17 (resolved by ReSpec 2.1.10)
  • [OASIS] make sure the WG name is "OASIS Open Services for Lifecycle Collaboration (OSLC) OP" (see https://github.com/oslc-op/oslc-specs/issues/221)

Main links

Clone this wiki locally