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
- Create a milestone by the name of the release [example: Milestone 6.0.0].
- 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]. - Add any breaking changes intended for the release to that milestone.
- 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
- For example, for a new major version 8, searches might include:
- Create an issue to raise the minimum versions of dependencies [example: Enhancement: Raise minimum versions of dependencies for v8]
- Create two new branches off
main
in the project repository (not a personal fork):v${major}
v${major}-canary-auto-release
- Raise a PR from
v${major}-canary-auto-release
tomain
modifyingci.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 aspublish_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
.
- Change the
- Under
README.md
:- Add a link to a
v${major}--typescript-eslint.netlify.app
preview deploy environment on Netlify that you create for the branch.
- Add a link to a
- Merge this into
main
once reviewed and rebase thev${major}
branch.
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:
- Create a
v${major}
channel on the typescript-eslint Discord - Create a discussion with a table summarizing any proposed rule changes [example: Changes to configurations for 6.0.0]
- Post that discussion on the typescript-eslint Discord and on social media
- 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.
- Create a pinned issue offering to try out the new version's beta for consumers [example: Try out v8 beta on various influential community repos]
- Ask each community project 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.
- 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. 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:
- Create a discussion describing the suggested changes [example: Configs: Last round of "final" changes to configs for v6].
- Post this new discussion in the previous config changes one, in the typescript-eslint Discord, and on social media.
- 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
- Send a PR from
v${major}
tomain
[example: v6.0.0]. - 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 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.
- To signify these changes as breaking, the first line of the PR description must read as
- 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.
- Keep this post up-to-date as changes land in the
- Wait until all required PRs have been merged
- Write a blog post announcing the new release [example: Docs: Release blog post for v6], and land it in the
v${major}
branch. - 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.
- Promote it on the
- Once discussions have settled, traditional merge commit the PR on top of
main
by temporarily enabling that merge setting for the repo.
Non-breaking changes can be merged to main
or the major branch.
They don't need any special treatment.
3. Releasing the Version
- 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.
- 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. - 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:
- Mention in any relevant issue(s) that you intend to release an out-of-band release
- Post in a private maintenance Discord channel that you're working on it
- Send a pull request resolving the issue(s)
- Waiting up to a day (as reasonable) for approval before merging the PR
- Trigger the private release workflow to cause a new release
- Post back in those same issue(s) with a link to the newly released version(s)