Skip to content

Releasing

Jump to bottom
Daniel Imms edited this page Sep 16, 2023 · 28 revisions

Code freeze

xterm.js is released approximately once a month. As the release date approaches say around 3-5 days before the scheduled date the code is frozen, this means all PRs that are non-trivial or important bug fixes are deferred until after the release is done. This helps minimize the risk of bugs coming in at last second that could cause the need for a patch release. Create the next milestone, setting the deadline to the first week of the following month.

Release notes

As the date approaches the release notes need to be created. Here are the steps for this:

  1. Go to the releases page and create a new draft.
  2. Copy the content of the release notes template into the new release draft.
  3. Open the pull requests page and make sure that all recent pull requests have correct milestones attached to them as sometimes PRs get merged in without a milestone. While doing this, also check the referenced issues to make sure they are closed off and assigned to the milestone too.
  4. Open the pull requests page again and assign the release's milestone.
  5. Go through each of the PRs and make a line item under the heading that makes the most sense, use this format:
    • (#issue) via @author
  6. Go through the release and merge similar issues where it makes sense. Typically do this for internal improvements as they're not as important for end users, or for PRs which were done as a series, for example:
    • (#issue1, #issue2) via @author1, @author2
  7. Fill in compatible versions of addons in the release notes, see the following section on whether releases need to be done

Publishing the release

In a branch, create a PR with a name of the format vx.y.z. In that branch, update the xterm version number. If there were any code changes to an addon made during this milestone, a minor release of the addon should be done. To do this just bump the version of the addon's package.json and CI will trigger the release. For easy checking of whether there's a change needing a release compare the previous release's branch to master like this.

Use this branch to submit a PR and make sure CI passes. Once merged Azure Pipelines should release the new versions of the library and the addons in the publish step of the master branch build.

Now publish the GitHub release, by naming the release in the x.y.z format it should also create the version tag when the release is published.

Website

This step was automated by xtermjs/xterm.js#2482 but is currently broken xtermjs/xterm.js#2606

For every major and minor version the website should also be updated. To do this, trigger this workflow manually which will create a PR with the latest changes included. Merging the PR will deploy the website.

Verifying after publish

After publishing the build can be verified easily using the electron example in node-pty. Just clone that, update the dependency and run the project.

Once verified, close out the milestone (which should have 0 open issues).

Patch releases

In order to do a patch release you will need to checkout the released tag that you're releasing from:

git checkout 3.9.0

Then branch that off:

git checkout -b release/3.9

Cherry pick (or PR) changes that have already landed in master to that branch:

git cherry-pick <commit sha>

Update the version in package.json, save and create a new commit for the version:

git add .
git commit -m "v3.9.0"

Push to the remote:

git push --set-upstream origin release/3.9

Once the branch is ready, queue a manual build setting the FORCE_RELEASE variable to true. This should release force a release off the branch.

Now publish the GitHub release like in normal releases, by naming the release in the x.y.z format it should also create the version tag when the release is published.

Clone this wiki locally