DESCRIPTION
- A story about auto-generating version tags and release notes like https://github.com/capacitor-community/admob/releases
- Happy that package.json version and the GitHub version now match
- A story about shaping the deploy/release flow around that
Main Text
Managing product source code on GitHub is normal now, but how do you manage release versions?
Embarrassingly, until about six months ago I was not versioning releases for my products at all.
- All right, I added this feature
- All right, tests passed. Time to release.
- Manually change the version in package.json
- Merge into the product branch (GitHub Actions runs) and deploy!!
Well, nothing especially notable went wrong, but because I import package.json with resolveJsonModule: true to show the version in the app, forgetting to update it makes support harder when I need to confirm the version. I use GitHub, yet GitHub version tags were not being used, so there was no overview of what changed in which version. Wait—now that I think about it, it was full of problems.
So I decided to tackle it properly.
Setting Up np
First, add an npm package to the project. If there is no package.json at the top level, run npm init to add one. At this stage, confirm that version and repository exist. For example, something like this:
{
"name": "test",
"version": "1.0.0",
"description": "",
"main": "index.js",
"scripts": {
"test": "echo \"Error: no test specified\" && exit 1"
},
"repository": {
"type": "git",
"url": "git+ssh://git@github.com/test/test.git"
},
"author": "",
"license": "ISC",
"bugs": {
"url": "https://github.com/test/test/issues"
},
"homepage": "https://github.com/test/test#readme"
}
Then install np, the key package this time.
% npm install np --save-dev
This package was originally for version management when running npm publish, but if you read the options carefully, you can use it for things other than npm publish, so I use it that way. Let us try running it first.
% npx np --no-publish --yolo
--no-publish means "not npm publish" (do not release as an npm package). --yolo means "do not clean up node_modules or run tests." Change the options as needed. You can run tests here, but I run them in CI on production deploy, so I use --yolo.
Options are here: https://www.npmjs.com/package/np#usage
Then choose patch, minor update, or major update.
? Select semver increment or specify new version (Use arrow keys)
❯ patch 8.2.17
minor 8.3.0
major 9.0.0
prepatch 8.2.17-0
preminor 8.3.0-0
premajor 9.0.0-0
prerelease 8.2.17-0
After you choose, the following runs:
- Changes the version value in package.json
- Lists Git commit history from the last GitHub tag to here
- Tags Git
- Creates a draft release note on GitHub so you only need to click release (below)
So convenient!! And you can track release version and tag version on GitHub like this.
https://github.com/capacitor-community/admob/releases
Setting Up GitHub Actions
Change the deploy GitHub Actions to trigger on tags instead of branches.
on:
push:
tags:
- v[0-9]+.[0-9]+.[0-9]+
With this, a push tagged x.x.x deploys. If there is no tag, nothing deploys.
Closing
Now I no longer need to explain "this update is..." to stakeholders—I can just pass a URL like this.
https://github.com/capacitor-community/admob/releases/tag/v1.2.4
I forget things easily, so not having "wait, when did I change that?" helps a lot. If you are building a CI environment, try adding version management too.
By the way, I also recommend this article if you have time.
https://zenn.dev/rdlabo/articles/4a241cacc7e364be8066
See you next time.