Skip to content

EPIC checklist

Jump to bottom
Andrew Berezovskyi edited this page Feb 6, 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

ReSpec & ShapeChecker

  • CicleCI has Prettier configuration to check spec HTML correctness and formatting
    • install with npm install -g prettier
    • Run prettier --check specs/someFolder to obtain list of errors to fix.
    • Run prettier --write specs/someFolder to format the documents.
  • CicleCI has ShapeChecker configuration to check shapes and vocabs (NB! make sure -C flag is enabled to check shapes metadata)
  • Ensure latest ReSpec is used (link)
  • Ensure no critical ReSpec errors are present (see the ReSpec button in the top right corner)
  • Ensure no HTML errors are present in the spec draft (check via W3C) and also 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.
  • 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=".
  • 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).
  • dcterms:issued in .ttl shapes and vocab files, set to same date as publishDate
  • dcterms:hasVersion in .ttl shapes and vocab files, set to specStatus+revision e.g,PSD01
  • dcterms:source and dcterms:isPartOf need to be changed to point to their future locations on open-services. See https://github.com/oslc-op/oslc-specs/pull/407/files, e.g., https://docs.oasis-open-projects.org/oslc-op/rm/v2.1/ps01/requirements-management-spec.html
  • No ShapeChecker errors in the CircleCI build (link)\
  • Make sure all URIs in the Additional components are fully qualified (ref, added 2020-09-09)
  • Make sure Part # is NOT used for machine-readable artefacts in the Additional components (ref, added 2020-09-09)

Editorial

  • All issues in the milestone are resolved
  • RDF files (if any) have the license headers set correctly. NB! Do not put XML comments before the 2nd line; the first line must always be the XML declaration.
  • No broken links other than the stage-to-be-published
  • head section contains a meta element with name="description" and content="{same text as in the abstract}"
  • Remove Part n: from the titles of the Additional components for the vocabulary and shapes Turtle files.
  • Update references to obsolete PSDs to point to the latest revisions. See https://open-services.net/specifications/ for a list of obsolete publications.

NB! Check links using https://addons.mozilla.org/en-GB/firefox/addon/find-broken-links/ (http://validator.w3.org/checklink if the PR for the spec did not touch the links since the last WD), fixing all broken links, and fixing those permanent redirects that appear sensible. Do not replace links for redirects from 'external' to 'internal' URIs - for example, never replace a link to open-services.net/ns with a link to a specific format or version of a vocabulary. Check accessibility using https://achecker.ca/checker/index.php, fixing issues that seem important

OASIS

  • Release Draft created (TODO add a hyperlink here to the Release Draft once created, create one here)
  • Release ZIP uploaded (instructions, 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 (TODO add link)
  • PGB vote initiated (template, TODO add date)
  • PGB vote passed (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

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.
  • open-services.net redirects resolve to the current published specs/drafts (ask Andrew, info)
  • 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 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 (for the first-time publication under the Open Project)

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] 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