How to Maintain UPM Package Part 4: Managing Package Release with CLI
Originally published on Medium
This article is part of a series that discusses best practices of managing a UPM repository on GitHub. See part 1, part 2, and part 3.
In previous posts, we introduced an automatic release process powered by semantic-release and GitHub Actions. That setup publishes from every commit to the master branch, which is not suitable for everyone. Some developers prefer to choose versions manually for marketing or release planning reasons. Release-it is a generic CLI tool for versioning and package publishing tasks.
Demo for release-it tool
Get Started
Step 1, obtain a personal access token (release-it only needs “repo” access; no “admin” or other scopes). You can optionally add it to the environment to simplify the command, or you need to provide it before each CLI execution.
Step 2, install the release-it CLI globally via NPM.
npm install release-it -g
By default, release-it is interactive and allows you to confirm each task before execution. You can play with the dry-run option.
GITHUB_TOKEN=YOUR_TOKEN_HERE release-it --dry-run
# Add --no-git.requireCleanWorkingDir if you're playing with the configuration file locally.
release-it --dry-run --no-git.requireCleanWorkingDir
Interactive mode
Step 3, add .release-it.yml as below with an empty CHANGELOG.md, then commit to the Git repository.
It tells release-it to
- Generate changelog and save to
CHANGELOG.md. - Create a GitHub Release.
- Disable NPM if you want to submit to OpenUPM later.
Step 4, release-it!
$ GITHUB_TOKEN=YOUR_TOKEN_HERE release-it
🚀 Let's release release-it-upm (currently at 0.0.0)
Empty changelog? Select increment (next version): major (1.0.0)
√ npx auto-changelog -p
Changeset:
M CHANGELOG.md
? Commit (chore: release v1.0.0)? Yes
? Tag (1.0.0)? Yes
? Push? Yes
? Create a release on GitHub (Release 1.0.0)? Yes
🚀 https://github.com/favoyang/release-it-upm/releases/tag/1.0.0
🚀 Done (in 55s.)
You can avoid the interactive mode, by specifying a version (major, minor, or patch) and passing the --ci option.
$ GITHUB_TOKEN=YOUR_TOKEN_HERE release-it minor --ci
🚀 Let's release release-it-upm (1.0.0...1.1.0)
Changelog:
- dummy feature 001 b24e5e6
√ npx auto-changelog -p
Changeset:
M CHANGELOG.md
√ Git commit
√ Git tag
√ Git push
√ GitHub create release
🚀 https://github.com/favoyang/release-it-upm/releases/tag/1.1.0
🚀 Done (in 30s.)
Further reading
To customize release-it to your own case, please check out hooks and plugins. E.g. you can use the after:release hook to split a UPM branch, generate DLLs, and create a upm/ prefixed Git tag.
Reese Schultz is also working on an alternative tool called ubump, a CLI designed specifically for releasing UPM packages and more friendly for monorepo. The project is young and lacking features like generating a changelog, but still looks promising. We will revisit it when it gets mature.
Conclusions
This tutorial shows how to manage package release with CLI. Please check out the example project: favoyang/release-it-upm.