Skip to content

Publication guidelines

Jump to bottom
Andrew Berezovskyi edited this page Sep 9, 2021 · 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
    1. NB! VSCode plugin bundles a new version of Prettier. We are sticking to [email protected].
  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.

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

EPIC checklist

Copy it from EPIC checklist

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.

PGB notice template

Send to [email protected] and cc [email protected]:

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.

The package is attached. Leave comments here or under %EPIC_URI%

Regards,
Andrew on behalf of the OSLC OP maintainers

PGB ballot template (only for PSDs, further ballots are opened by Chet)

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

Main links

Clone this wiki locally