Skip to content

Publication guidelines

Jump to bottom
Andrew Berezovskyi edited this page Aug 27, 2020 · 47 revisions

Overall process

  1. Make sure Prettier is run before you push: prettier --write specs/%your_spec%/. Pro tip: run prettier on save using https://marketplace.visualstudio.com/items?itemName=esbenp.prettier-vscode#user-content-format-on-save
  2. Make sure the initial Working Draft is published on Github Pages (see here). NB! Do not use PSD or PS stage there, only WD stage may be used without a formal vote.
  3. Notify the PGB at least 14 days before the vote begins about the intent to publish a spec. See below for a template of the letter to the PGB.
  4. Create a milestone for the document to be published (link)
  5. File a new EPIC issue (an issue that just points to a collection of other issues or checklist items) under oslc-specs and use the checklist below as the issue description. Also put the EPIC issue under the newly created milestone.
  6. Work through all the ReSpec and editorial issues before submitting the spec for a PGB vote (see here for how to link your issue in a PR to be closed automatically).
  7. Submit a PGB vote by creating a poll or ask someone from the PGB to do it for you. See below for a template of the letter to the PGB.
  8. Announce ballot results and capture vote tally on the 7th day. NB! If you fail to announce the results on the day listed in the spec as the publication day, OASIS will require you to produce a new ZIP archive with the date of publication set to the date when the ballot results were announced.
  9. Merge all PRs but do not tag the repository just yet. This is because OASIS may require fixes after the PGB vote is concluded.
  10. Request publication from OASIS (link, example).
  11. Tag the commit %shortname%-v%version%-%STAGE%%REVISION% (e.g. rm-v2.1-PSD02) once the spec has been deployed to staging AND Chet has given his LGTM in the issue you created in the oasis-open-projects/administration repo.

PGB notice template

Subject: Formal notice of intent to publish %PRODUCT_NAME_FULL%

Dear PGB members,

The rules require us to notify you at least 14 days before submitting the ballots for the spec drafts publication. We are hereby notifying you of the OP intention to publish %PRODUCT_NAME_FULL% in 2 weeks’ time.

Working draft can be found here: %WD_URI%

The PSD preparation work is tracked in the following issues where you can leave comments at any time:

%EPIC_URI% %PR_URI_IF_EXISTS%

Regards,
OSLC OP maintainers

PGB ballot template

Title: %PRODUCT_NAME_FULL% ballot

Question:

Do the PGB members approve publishing %PRODUCT_NAME% as the %PRODUCT_STAGE_VERSION%?

Release materials are located under https://github.com/oslc-op/oslc-specs/releases

The ballot opens immediately and will close on %DATE+7d%.

Answers:

  1. YES, approve the publication
  2. NO, reject the publication

EPIC checklist

WORKING DRAFT (TODO make it a link to the current WD)

Preflight

  • Read the guidelines
  • 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.
  • 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)

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

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)
  • PGB vote initiated (template, TODO add date)
  • PGB vote passed (TODO add hyperlink to the announcement email)
  • OASIS publication request filed under oasis-open-projects/administration (TODO add link)
  • 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 (Andrew)
  • 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)

Release ZIP generation steps

  1. Run a local web server using python3 -m http.server 8000 or python -m SimpleHTTPServer 8000 or npm install -g local-web-server and then run ws. Access from local filesystem may cause JS errors connected with security around local file access. You browser may render file and http protocols differently. DO NOT USE BROWSERSYNC AT THIS STAGE! DO NOT SIMPLY OPEN FILES FROM THE FILESYSTEM, YOU MUST RUN A WEB SERVER!
  2. Save the spec snapshot using Chrome in the Incognito mode in the HTML format. This disables extensions that may affect the rendering of the spec.
  3. Create a new folder.
  4. Move all generated files.
  5. Copy all images and RDF files there too.
  6. Check every file for HTML errors via https://validator.w3.org/nu/#file
  7. Zip up the directory.
  8. Create a draft release/pre-release and attach the ZIP.
  9. Link to the draft (pre-)release from the PR.

Main links

Clone this wiki locally