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 a fully automatic way of package release process powered by the semantic-release tool and GitHub Actions. Besides many benefits, the most significant change is to apply the continuous releasing strategy, every commit to the master branch creates a release. But it may be not suitable for everyone. Especially for developers who want to control their version manually for marketing reasons. The alternative way is to use an integrated command-line tool to manage the process. Release-it is a generic CLI tool to automate versioning and package publishing related 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.