Releasing RIDDL

This is a “how to” guide on releasing the software.

Make sure everything tests correctly from a clean start.

% cd riddl # top level directory of repository 
% sbt
> ; clean ; test ; test ; test
> project plugin
> scripted  
...
[info] All tests passed.

If all tests do not pass, stop and fix the software. Note that the tests are run three times quickly. This tends to expose parallelism issues.

> sbt stage
...
[info] Main Scala API documentation successful.
[success] Total time: 29 s, completed Sep 5, 2022, 12:05:58 PM

If this task does not successfully complete, stop and fix the documentation which is likely to be references to Scala classes in the docs between [[ and ]]

Now that riddlc is staged, run the hugo command on a large multi-file specification such as the Improving App. This will expose any language change issues. If this doesn’t pass, go back and fix the software again and start from scratch. The test case named RunRiddlcOnArbitraryTest will do this for you if you clone that repo and adjust the paths in that test case for your clone. The test will just succeed if it can’t find those files locally.

You’ve probably made changes as a result of the above. Commit those to a branch (except the change to RunRiddlcOnArbitraryTest) and push it to GitHub (origin)

Use the branch you just created on GitHub to make a pull request and wait for the workflow(s) to complete. If it does not pass all workflows, resolve those issues and start this releasing process from the beginning. If it does pass the workflows, merge it to main branch

git checkout main

Make sure there are no changes in your working tree. One way to do this is to

get status

If that says:

On branch main
Your branch is up to date with 'origin/main'

nothing to commit, working tree clean

then you’re okay to proceed; otherwise, fix the issues and restart this releasing process.

We are trying to follow semantic versioning rules for RIDDL. Use GitHub’s features to assess what has changed in the version you are releasing. If the language has changed syntax or semantics you must increase the major version number. Try to batch such changes.

Pick a version number, x.y.z, based on current tagged version and the nature of the changes and the semver.org rules.

Now that:

• you’ve got things working,
• all your code changes are committed and pushed,
• you’ve got a clean working tree on the main branch,
• you’ve picked a version number

it is time to

1. Formulate a short description string for the release
2. Run this:

> git tag -a ${x.y.z} -m "${release description}"
> sbt show version # confirm it is the version you just set
> git push --tags

1. First, publish the artifacts to oss.sonatype.org

% cd riddl
% sbt publishSigned

1. When that is complete, log in to Sonatype OSS Repo
2. Check the staged artifacts for sanity. All modules should be published with the same release number
3. Close the repository and add the release number in the notes
4. Press the Release button to publish to maven central

% sbt
> project riddlc
> Universal/packageBin
> Universal/packageOsxDmg
> graalvm-native-image:packageBin
> 

open https://github.com/ossuminc/riddl/releases/new

• pick the tag that you just made
• write the release notes

• Click the area on github new release page that says:

Attach binaries by dropping them here or selecting them.

• Attach these files:
  • riddl/riddlc/target/universal/riddlc-${x.y.z}.zip
  • riddl/riddlc/target/universal/riddlc-${x.y.z}.dmg

• Open https://github.com/ossuminc/riddl/edit/main/actions/get-riddlc/action.yaml
• Scroll to the bottom of the page
• Update the version number value set in the version variable to the ${x.y.z} version you released above.
• Commit, push, merge.

The change to this file does not need to be included in the release tag. Always do this last because other projects are dependent on this action and the action is dependent on the uploaded artifacts.