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​

PerUsers > 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 therecommended sets for 5.0.0].
3. Add any breaking changes intended for the release to that milestone.
4. Search for source code comments (excludingCHANGELOG.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 offmain in the project repository (not a personal fork):
   • v${major}
   • v${major}-canary-auto-release
7. Raise a PR fromv${major}-canary-auto-release tomain modifyingci.yml workflow and README.md [example:chore: add auto-canary release for v6]:
   • ci.yml:
     • Underpush: >branches: at the beginning of the file, add a- v${major} list item.
     • Add apublish_canary_version_v${major} step the same aspublish_canary_version except:
       • Change theif condition's branch check to:if: github.ref == 'refs/heads/v${major}'.
       • Its publish command should benpx nx release publish --tag rc-v${major} --verbose.
   • README.md:
     • Add a link to av${major}--typescript-eslint.netlify.app preview deploy environment on Netlify that you create for the branch.
   • docusaurus.config.mts: updating thesupportedMajorVersion variable
   • Merge this intomain once reviewed and rebase thev${major} branch.

1a. Shared Config Changes​

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

1. Create av${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 thev${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 proposedShared Config Changes are merged into thev${major} branch, send a draft PR to each project with the new beta version.

1c. 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 fromv${major} tomain [example:v6.0.0].
2. Change allbreaking change PRs to target thev${major} branch.
   • To signify these changes as breaking, the first line of the PR description must read asBREAKING CHANGE:, and second line should briefly summarize the changes.
   • It is important to note that when merged the commit message must also includeBREAKING CHANGE: as the first line in order fornx 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 thev${major} branch.
4. Send a PR to thev${major} branch that adds the old major version toUsers > 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 thev${major} branch.
7. Let the release wait forat 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 ofmain by temporarily enabling that merge setting for the repo.

3. Releasing the Version​

1. Discuss with the maintainers to be ready for anout-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 theCURRENT_MAJOR_VERSION environment variable to the new major version integer, such as9
   2. Re-deploy thev${major} branches listed inUsers > 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​

PerUsers > 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)