Skip to main content


As Telescope matures, we are trying to improve our build, release, and deployment processes and tools. This is an on-going effort, and all maintainers should try to keep this document up-to-date to reflect our current practices.


In order for the automated release process to work, you must do the following:

Create a Release

When we release Telescope, we need to do a number of things:

  • run our linters, tests, and make sure the code is working as best we can
  • set a new version number in package.json
  • create a new release commit, git tag, and push to our upstream GitHub repo
  • generate a changelog
  • create a Release on GitHub

We use the npm-version command line tool (with pnpm version) to help us automate the release process.

Using npm-version

To create a new release, follow these steps:

  1. Make sure your master branch is up-to-date, and you have the most recent git tags in your repo: git pull upstream master --tags.
  2. Make sure that the latest commit on master is passing CI on GitHub Actions, and that you are sitting on the same commit locally (i.e.,git show or git log and compare the git SHA).
  3. Determine what the new version string should be based on semantic versioning. New version should be a valid semver string. In our project, that would usually be minor (e.g. 1.5.0, 1.6.0, 1.7.0) or major (e.g. 1.0.0, 2.0.0). See npm-version docs to learn more about what options are available for the new version string.
  4. Use pnpm version <new-version-string> -m "Release message" to trigger the automated release workflow. For example, pnpm version minor -m "Release 1.6.0" will increase the minor version of the project (1.5.x -> 1.6.0). To make a major release, we can use pnpm version major -m "Release 2.0.0" (1.x.x to 2.0.0).

npm-version will NO LONGER run tests locally so please double-check step 1-4 above. When run, npm-version will also bump the version in package.json, create a new git tag and push both the code and the tags to upstream master (which you should have configured to point to at this point). That will trigger our release workflow, which will run all tests in the cloud. If tests finish successfully, the release workflow will proceed to generate a changelog and create a new GitHub Release.


Our release processes updated a number of domains, depending on what you do:

NameDomainUpdated When Change To
Loginlogin.telescope.cdot.systemsmaster (automatic)
Stagingdev.telescope.cdot.systemsmaster (automatic)
Productiontelescope.cdot.systemsrelease (git tag)
Zeit (automatic)