Guidelines for publishing machine readable files

Intro

Most of the machine-readable files have a canonical URI under http://open-services.net/ns/. The authoritative copies are uploaded to OASIS document archive. A process is needed to keep the two in sync.

Process

1. Wait for the specification to be published under https://docs.oasis-open-projects.org/oslc-op/. Rationale: we want to use an authoritative copy for the subsequent operations. Do not use files from a Github repo!
2. Create a new branch and copy new machine-readable files under https://github.com/oslc-op/website/tree/master/content/ns/.
3. Follow the instructions in https://github.com/oslc-op/website/blob/master/content/ns/README.md to generate RDF/XML, N-Triples, and JSON-LD files from the authoritative Turtle file(s).
4. File a pull request under https://github.com/oslc-op/website/. Make sure to secure review approval during the OP call or from one PGB or TSC member.
5. File a corresponding pull request with the changes to the https://github.com/oslc-op/website-content-negotiation/blob/master/config/conneg.yml file. Make sure the URI for the HTML file resolves; it is recommended to try a name of one resource after the hash sign to see that the HTML anchors are working. Make sure to update the core_version value if the revision of the spec in question references a newer OSLC Core revision.
6. Merge the https://github.com/oslc-op/website-content-negotiation AFTER the corresponding PR to https://github.com/oslc-op/website/ has been merged AND DEPLOYED. Please refer to https://github.com/oslc-op/website/actions/workflows/deploy.yml to check the deployment of the website changes.
7. SSH to the OSLC server and update the content negotiation app manually:

   cd workspace/oslc-site-content-negotiation/
   # check the application is running OK before commencing upgrade
   pm2 status
   pm2 save
   pm2 stop negotiation
   # in case pm2 package was updated
   pm2 update
   git pull
   pm2 start negotiation.js --update-env --name=negotiation
   pm2 status
   pm2 save
   

8. Make sure the uptime page shows the OSLC Core vocab monitor as UP: https://stats.uptimerobot.com/wp296fgr
9. Run the tests in https://github.com/oslc-op/website-content-negotiation/blob/master/test.sh to make sure the update was successful: ./test.sh -p. You are looking for an output looking similar to:

   ./test.sh -p
   Running production tests
   Running tests on 'ns/core'
   Running tests on 'ns/core/shapes/3.0'
   Running tests on 'ns/cm'
   Running tests on 'ns/cm/shapes/3.0'
   Running tests on 'ns/rm'
   Running tests on 'ns/rm/shapes/2.1'
   Running tests on 'ns/qm'
   Running tests on 'ns/qm/shapes/2.1'
   Running tests on 'ns/config'
   Running tests on 'ns/am'
   Running tests on 'ns/asset'
   Running tests on 'ns/auto'
   Running tests on 'ns/perfmon'
   ALL TESTS PASSED