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. Search for source code comments (excluding CHANGELOG.md files) that mention deprecated code and/or a todo for the new major version, and create corresponding issues in that milestone.
   • For example, for a new major version 8, searches might include:
     • /deprecated|todo/i
     • /v8/i
     • /todo.*v?8/i
5. Create an issue to raise the minimum versions of dependencies [example: Enhancement: Raise minimum versions of dependencies for v8]
6. Create two new branches off main in the project repository (not a personal fork):
   • v${major}
   • v${major}-canary-auto-release
7. Raise a PR from v${major}-canary-auto-release to main modifying ci.yml workflow and README.md [example: chore: add auto-canary release for v6]:
   • ci.yml:
     • Under push: > branches: at the beginning of the file, add a - v${major} list item.
     • Add a publish_canary_version_v${major} step the same as publish_canary_version except:
       • Change the if condition's branch check to: if: github.ref == 'refs/heads/v${major}'.
       • Its publish command should be npx nx release publish --tag rc-v${major} --verbose.
   • README.md:
     • Add a link to a v${major}--typescript-eslint.netlify.app preview deploy environment on Netlify that you create for the branch.
   • docusaurus.config.mts: updating the supportedMajorVersion variable
   • Merge this into main once reviewed and rebase the v${major} branch.
8. Configure the https://github.com/ldez/gha-mjolnir action to auto-close issues when PRs are merged to the v${major} branch (GitHub doesn't by default): see close-v8-issues.yml for reference

1a. Shared Config Changes

Major versions are our only real chance to change the values in our stable recommended* and stylistic* configs. In parallel to the general PR flow of the major version:

1. Create a v${major} channel on the typescript-eslint Discord
2. Create a discussion with a table summarizing any proposed rule changes [example: Changes to configurations for 6.0.0]
3. Post that discussion on the typescript-eslint Discord and on social media
4. Once the greater of (1 month) and (discussion settling down) has passed, file an issue and send a corresponding PR to the v${major} branch making the corresponding changes [example: Configs: Apply changes to config presets for v6]

1b. Voluntary Community Testing

In parallel to the shared config changes work, make sure to test out the beta version on popular community projects willing to try it out.

1. Create a pinned issue offering to try out the new version's beta for end users (example: Try out v8 beta on various influential community repos)
   • Ask each community repo if they'd be interested in trying out the new version, such as in their Discord or on their issue tracker.
   • Each community project that's indicated willingness to receive a PR should have one.
2. Create a pinned issue offering to try the new version's beta for downstream plugins (example: Try out v8 beta on various influential plugins)
   • These PRs can be sent without asking, as a friendly courtesy.
3. Once the proposed Shared Config Changes are merged into the v${major} branch, send a draft PR to each project with the new beta version.

1c. Tracking Issue for Support

If there are behavioral breaking changes in the new major version, consider also creating a tracking issue showing support across popular plugins. To do this:

1. Create a pinned issue (example: 📈 Tracking: typescript-eslint v8 support)
2. For each plugin you're familiar with, try sending a draft PR to them with a description of what you're doing (example: chore: bump typescript-eslint to v8)
3. Make sure you're subscribed to notifications on that issue and any PRs, and update the table regularly

1d. Post Community Testing Config Touchups

There may be additional changes to preset configs discovered as part of the community testing. If that's the case:

1. Create a discussion describing the suggested changes [example: Configs: Last round of "final" changes to configs for v6].
2. Post this new discussion in the previous config changes one, in the typescript-eslint Discord, and on social media.
3. Once the greater of (2 weeks) and (discussion settling down) has passed

If possible, we prefer to avoid making a second round of config changes. These should only be done for feedback that consistently comes up in community testing.

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 nx release 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. Write and share out a blog post announcing the new beta [example: Docs: Blog post describing changes & migration strategy for v5->v6].
   • Keep this post up-to-date as changes land in the v${major} branch.
4. Send a PR to the v${major} branch that adds the old major version to Users > Releases > Old Release Documentation
5. Wait until all required PRs have been merged
6. Write a blog post announcing the new release [example: Docs: Release blog post for v6], and land it in the v${major} branch.
7. 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 social media to get some additional attention.
8. Once discussions have settled, traditional merge commit the PR on top of main by temporarily enabling that merge setting for the repo.

:::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. nx release 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.
   • Example release notes: v6.0.0, v5.0.0
3. Update Netlify deploys for old sites:
   1. Update the CURRENT_MAJOR_VERSION environment variable to the new major version integer, such as 9
   2. Re-deploy the v${major} branches listed in Users > Releases > Old Release Documentation
4. Finally, post the release on social media 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)