How to Maintain UPM Package Part 4: Managing Package Release with CLI
- This article is part of a series that discussing best practices of managing a UPM repository on GitHub. See part 1, part 2, and part 3.
- Feel free to check out openupm.com to discover more open-source UPM packages, and support OpenUPM at patreon.com/openupm.
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 significate 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.
Get Started
Step 1, obtain a personal access token (release-it only needs “repo” access; no “admin” or other scopes). You can optional 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 -gBy 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 configuration file locally.
release-it --dry-run --no-git.requireCleanWorkingDir
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 -pChangeset:
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 specify 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`](https://github.com/favoyang/release-it-upm/commit/b24e5e631af47d8159020570d569dc710eb0041e)
√ 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 checkout 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.
Feel free to check out openupm.com to discover more open-source UPM packages, and support OpenUPM at patreon.com/openupm.
