Release Checklist

1. Make sure the CI checks are passing.

   The current master branch should be passing all CI tests. All the badges in the README should be green and everything in the actions tab for the current commit should be passing. CI failures will inhibit some of the automatic deploy process for a release so you can't just ignore them.

2. Make sure you are working from an up to date and clean local checkout. Your local remote names may differ, but make sure you've pulled in the latest remote code and don't have anything locally that might foul up the process.

   git checkout master
   git pull --rebase
   git reset --hard
   git clean -dxff

3. Figure out what the next release version will be following semver spec. For the purpose of this checklist we'll reference this as $SEMVER

   export SEMVER=x.y.z

4. Edit and update the reference to the latest version tag action.yml to the v$SEMVER for the next release.

   sed -i -e "/image:/s/:v.*/:v$SEMVER/" action.yml
   

5. If the output of --help has changed since the last release update it in the README.md, and optionally update mentions of example tags to the latest.

6. Create a new rockspec for the new release:

   make rockspecs/fontproof-$SEMVER-1.rockspec
   

7. Stage the modified files and the new rockspec:

   git add action.yml README.md rockspecs/fontproof-$SEMVER-1.rockspec
   

8. Commit with a conventional commits compatible message:

   git commit -m "chore: Release $SEMVER"
   

9. Tag the new commit (with v prefix):

   git tag v$SEMVER
   

10. Push the tag and commit to GitHub (Warning: Push the tag first then the branch so as not to introduce a race condition in CI because the newly posted rockspec will be looking for the tag, not the branch.)

    git push --tags
    git push
    

    Note when pushing tags depending on how you updated your local tag set Git may throw an error about rejecting a couple tags (e.g. latest and v2). These can be ignored as they are updated remotely on deploy.

11. Generate a packed source rock to attach to the release for people that don't want to or cannot use LuaRocks (Note this must be done after pushing the tag in the previous step!).

    luarocks pack rockspecs/fontproof-$SEMVER-1.rockspec
    

12. Publish a release based on the tag to GitHub Releases:

    1. Open the tag on GitHub and create a release out of it:

       xdg-open https://github.com/sile-typesetter/fontproof/releases/new?tag=v$SEMVER
       

       • Set the release title to: FontProof v$SEMVER
       • Use the Git commit log to distill down end user relevant changes into a bullet point release notes.
       • Attach the fontproof-$SEMVER-1.src.rock created in the last step.

    2. Optionally use the gh cli tool to do the same:

       gh release create v$SEMVER -t "FontProof v$SEMVER" fontproof-$SEMVER-1.src.rock
       

       When promted with at editer enter the bullet point release notes distilled from the Git commit log.

13. Eat cake. At this point the release should show up on LuaRocks.org as soon as the CI runs are complete.