Skip to main content

Releases

Users > Releases describes how our automatic releases are done. There is generally no maintenance activity we need to take for the weekly releases.

However, there are two kinds of releases we infrequently go through that each require manual effort.

Major Releases​

Per Users > Releases > Major Releases, we infrequently release major versions with accumulated breaking changes.

1. Pre-Release Preparation​

  1. Create a milestone by the name of the release [example: Milestone 6.0.0].
  2. If an issue for changes to recommended rule configs doesn't yet exist, create one [example: Changes to the recommended sets for 5.0.0].
  3. Add any breaking changes intended for the release to that milestone.
  4. Create two new branches off main in the project repository (not a personal fork):
    • v${major}
    • v${major}-canary-auto-release
  5. Raise a PR from v${major}-canary-auto-release to main modifying the ci.yml workflow [example: chore: add auto-canary release for v6]:
    • Under pushes: at the beginning of the file, add an - v${major} list item.
    • Add a publish_canary_version_v${major} step the same as publish_canary_version except:
      • Add the condition: if: github.ref == 'refs/heads/v${major}'.
      • Its publish command should be npx lerna publish premajor --loglevel=verbose --canary --exact --force-publish --yes --dist-tag rc-v${major}.
    • Merge this into main once reviewed and rebase the v${major} branch.

2. Merging Breaking Changes​

  1. Send a PR from v${major} to main [example: v6.0.0].
  2. Change all breaking change PRs to target the v${major} branch.
    • To signify these changes as breaking, the first line of the PR description must read as BREAKING CHANGE:, and second line should briefly summarize the changes.
    • It is important to note that when merged the commit message must also include BREAKING CHANGE: as the first line in order for lerna to recognize it as a breaking change in the release notes. If you miss this it just means more manual work when writing the release documentation.
  3. Wait until all required PRs have been merged
  4. Let the release wait for at least 1 week to allow time for early adopters to help test it and discuss the changes.
    • Promote it on the @tseslint twitter to get some additional attention.
  5. Once discussions have settled, rebase merge the PR on top of main.
note

Non-breaking changes can be merged to main or the major branch. They don't need any special treatment.

3. Releasing the Version​

  1. Discuss with the maintainers to be ready for an out-of-band release. Doing this manually helps ensure someone is on-hand to action any issues that might arise from the major release.
  2. Prepare the release notes. Lerna will automatically generate the release notes on GitHub, however this will be disorganized and unhelpful for users. We need to reorganize the release notes so that breaking changes are placed at the top to make them most visible. If any migrations are required, we must list the steps to make it easy for users.
  3. Finally, tweet the release on the @tseslint twitter with a link to the GitHub release. Make sure you include additional information about the highlights of the release!

Out-of-Band Releases​

Per Users > Releases > Out-of-Band Releases, we may manually trigger a new release for a rare emergency such as a critical regression. If that happens:

  1. Mention in any relevant issue(s) that you intend to release an out-of-band release
  2. Post in a private maintenance Discord channel that you're working on it
  3. Send a pull request resolving the issue(s)
  4. Waiting up to a day (as reasonable) for approval before merging the PR
  5. Trigger the private release workflow to cause a new release
  6. Post back in those same issue(s) with a link to the newly released version(s)