Versions
Index
Powered by

Manage Releases

Releases are when a project formally publishes a new version so the community can use it. There are two types of releases:

  • Regular releases that follow semantic versioning and are considered production-ready.
  • Prereleases that are not considered production-ready and are intended to give the community a preview of upcoming changes.

Release Manager

One member of the Technical Steering Committee (TSC) is assigned to manage each scheduled release. The release manager is determined at the TSC meeting the day before the release.

The release manager is responsible for:

  1. The scheduled release on Friday.
  2. Monitoring issues over the weekend.
  3. Determining if a patch release is necessary on Monday.
  4. Publishing the patch release (if necessary).

The release manager should seek input from the whole team on the Monday following a release to double-check if a patch release is necessary.

The release manager needs to have access to ESLint’s two-factor authentication for npm in order to do a release.

Release Communication

Each scheduled release is associated with an autogenerated release issue (example). The release issue is the source of information for the team about the status of a release and contains a checklist that the release manager should follow.

Process

On the day of a scheduled release, the release manager should follow the steps in the release issue.

All release-related communications occur in a thread in the #team channel on Discord.

On the Monday following the scheduled release, the release manager needs to determine if a patch release is necessary. A patch release is considered necessary if any of the following occurred since the scheduled release:

  • A regression bug is causing people’s lint builds to fail when it previously passed.
  • Any bug that is causing a lot of problems for users (frequently happens due to new functionality).

The patch release decision should be made as early on Monday as possible. If a patch release is necessary, then follow the same steps as the scheduled release process.

In rare cases, a second patch release might be necessary if the release is known to have a severe regression that hasn’t been fixed by Monday. If this occurs, the release manager should announce the situation on the release issue, and leave the issue open until all patch releases are complete. However, it’s usually better to fix bugs for the next release cycle rather than doing a second patch release.

After the patch release has been published (or no patch release is necessary), close the release issue and inform the team that they can start merging in semver-minor changes again.

Release Parameters

The following tables show examples of the option to select as RELEASE_TYPE when starting eslint-js Release (the @eslint/js package release) and eslint Release (the eslint package release) jobs on Jenkins to release a new version with the latest features. In both jobs, main should be selected as RELEASE_BRANCH.

HEAD Version Desired Next Version eslint-js Release
RELEASE_TYPE
9.25.0 9.25.1 patch
9.25.0 9.26.0 minor
9.25.0 10.0.0-alpha.0 alpha.0
10.0.0-alpha.0 10.0.0-alpha.1 alpha
10.0.0-alpha.1 10.0.0-beta.0 beta
10.0.0-beta.0 10.0.0-beta.1 beta
10.0.0-beta.1 10.0.0-rc.0 rc
10.0.0-rc.0 10.0.0-rc.1 rc
10.0.0-rc.1 10.0.0 major
HEAD Version Desired Next Version eslint Release
RELEASE_TYPE
9.25.0 9.25.1 or 9.26.0 latest
9.25.0 10.0.0-alpha.0 alpha
10.0.0-alpha.0 10.0.0-alpha.1 alpha
10.0.0-alpha.1 10.0.0-beta.0 beta
10.0.0-beta.0 10.0.0-beta.1 beta
10.0.0-beta.1 10.0.0-rc.0 rc
10.0.0-rc.0 10.0.0-rc.1 rc
10.0.0-rc.1 10.0.0 latest

When releasing a new version of the previous major line, the option to select as RELEASE_TYPE depends on whether the HEAD version is a prerelease or not. In both jobs, the corresponding development branch (for example, v9.x-dev) should be selected as RELEASE_BRANCH.

HEAD Version Previous Major Line Version Desired Next Version eslint-js Release
RELEASE_TYPE
10.0.0-alpha.0 9.25.0 9.25.1 patch
10.0.0-alpha.0 9.25.0 9.26.0 minor
10.0.0 9.25.0 9.25.1 maintenance.patch
10.0.0 9.25.0 9.26.0 maintenance.minor
HEAD Version Previous Major Line Version Desired Next Version eslint Release
RELEASE_TYPE
10.0.0-alpha.0 9.25.0 9.25.1 or 9.26.0 latest
10.0.0 9.25.0 9.25.1 or 9.26.0 maintenance

Emergency Releases

An emergency release is unplanned and isn’t the regularly scheduled release or the anticipated patch release.

In general, we try not to do emergency releases. Even if there is a regression, it’s best to wait until Monday to see if any other problems arise so a patch release can fix as many issues as possible.

The only real exception is if ESLint is completely unusable by most of the current users. For instance, we once pushed a release that errored for everyone because it was missing some core files. In that case, an emergency release is appropriate.

Major Releases

This section describes additional tasks that should be done in ESLint repositories and infrastructure during a major release cycle. A major release cycle includes prereleases and the final release of a new major version of ESLint.

For simplicity, let v9.x be the current version, and v10.0.0 the new major version.

The following branches in the eslint/eslint repository are of importance for this release cycle:

  • main: All the latest development always happens on this branch, and that also applies to major release cycles. This means that breaking changes should be merged into this branch, along with new features, bug fixes and everything else we usually merge into this branch. Prerelease versions and the final major version will be published from this branch.
  • next: Branch for the latest prerelease documentation (https://eslint.org/docs/next/). This branch is automatically updated during the release process.
  • v9.x-dev: Branch for v9.x maintenance. This branch starts from the last v9.x release commit before the first v10 prerelease. All new v9.x versions (if needed) will be published from this branch.
  • v9.x: Branch for the ESLint v9.x documentation (https://eslint.org/docs/v9.x/). This branch is automatically updated during the release process. Note that this branch is needed only after the final v10.0.0 release. Until then, v9.x is still the latest version, and the documentation branch for it is latest (https://eslint.org/docs/latest/).

First Prerelease

Work on the first prerelease (alpha.0) starts when the last planned v9.x release is concluded.

  • On Netlify, open the docs-eslint project. Under Project Configuration > Build & Deploy > Continuous deployment, find Dependency management. Check if the configured version of Node.js satisfies requirements of the new major version of ESLint. If not, update it to a new version of Node.js.
  • On Jenkins, check if the installed version of Node.js satisfies requirements of the new major version of ESLint. If not, install a new version of Node.js.
  • In the eslint/eslint.org repository, submit a PR to set upcomingVersionPrereleaseType = "alpha" in tools/release-data.js. This is to announce the prerelease in the version list on the https://eslint.org/ homepage. The PR can be merged as soon as it is approved.
  • In the eslint/eslint.org repository, submit a PR to enable /docs/next/* proxying in src/static/redirects.njk. The PR should be reviewed and approved in time, but merged right after ESLint 10.0.0-alpha.0 is released.
  • In the eslint/eslint.org repository, submit a PR to update the Current Release Lines table in src/content/pages/version-support.md: add v10.x with Status “Current” and First Release as the planned first prerelease date (also add <br>(prerelease) after the date); update v9.x status to “Maintenance”. The PR should be reviewed and approved in time, but merged right after ESLint 10.0.0-alpha.0 is released.
  • In the eslint/eslint repository, submit a PR to add legacy-peer-deps = true in the .npmrc file. This is to ensure that npm install works in CI and locally for developers after the prerelease, because some dependencies (e.g., @eslint-community/eslint-utils) have eslint declared as a peer dependency with a range that prerelease versions like 10.0.0-alpha.0 don’t satisfy. Additionally, add --legacy-peer-deps CLI flag to npm install commands for which the .npmrc file doesn’t apply, like npm install ../eslint in types-integration.yml. The PR can be merged as soon as it is approved.
  • In the eslint/eslint repository, submit a PR to update ranges for peer dependency eslint in packages/js/package.json, and ranges for dependency @eslint/js and peer dependency eslint in packages/eslint-config-eslint/package.json to include v10 and its prereleases. This is to ensure that the corresponding version of @eslint/js is used when linting. The PR can be merged as soon as it is approved.
  • In the eslint/eslint repository, create an issue to track all temporary changes that should eventually be reverted or modified (e.g., to remove legacy-peer-deps settings when possible).

In this phase, we should also prepare infrastructure for v9.x maintenance:

  • In the eslint/eslint repository, create v9.x-dev branch that points to the latest release commit (e.g., to the 9.39.0 commit). On the Branches page, check if the branch is protected (it should already be, as its name matches a predefined pattern in branch protection rules).
  • In the eslint/eslint repository, submit a PR that adds v9.x-dev to the lists of branches that trigger CI checks in .github/workflows/* files. The PR should target the v9.x-dev branch and can be merged as soon as it is approved.
  • On Netlify, open the docs-eslint project. Under Project Configuration > Build & Deploy > Continuous deployment, find Branches and deploy contexts. Add v9.x-dev to Branch deploys. This is to enable deploy previews on PRs that target the v9.x-dev branch. While there, check if the next branch is also included in Branch deploys (it should already be).
  • On Jenkins, in configurations for the eslint Release and eslint-js Release jobs, add v9.x-dev to the list of choices for the RELEASE_BRANCH parameter.

Subsequent Prereleases

  • When it is expected that the next planned prerelease will advance from alpha to beta, or from beta to rc, in the eslint/eslint.org repository submit a PR to update upcomingVersionPrereleaseType accordingly in tools/release-data.js. The PR can be merged as soon as it is approved.

Final Release

  • When it is expected that the next planned release will be the final v10.0.0 release, in the eslint/eslint.org repository submit a PR to update upcomingVersionPrereleaseType to null in tools/release-data.js. The PR can be merged as soon as it is approved.
  • In the eslint/eslint repository, create v9.x branch that points to the latest v9.x release commit (e.g., to the 9.39.0 commit).
  • On Netlify, open the docs-eslint project. Under Project Configuration > Build & Deploy > Continuous deployment, find Branches and deploy contexts. Add v9.x to Branch deploys. To trigger the first production deploy for testing purposes, find Build Hooks, copy the URL and then run curl -X POST -d '{}' <URL>?trigger_branch=v9.x in your terminal (<URL> is the build hook URL).
  • In the eslint/eslint.org repository, submit a PR to enable /docs/v9.x/* proxying in src/static/redirects.njk. The PR should be reviewed and approved in time, but merged right before ESLint 10.0.0 final is released.
  • In the eslint/eslint.org repository, submit a PR to redirect /docs/next/* and /docs/v10.x/* to /docs/latest/* in src/static/redirects.njk. The PR should be reviewed and approved in time, but merged right after ESLint 10.0.0 final is released.
  • In the eslint/eslint.org repository, submit a PR to update the Current Release Lines table in src/content/pages/version-support.md: update v10.x First Release date to the planned final ESLint v10.0.0 release date (also remove <br>(prerelease) after the date); set v9.x EOL Start date to the planned final ESLint v10.0.0 release date plus six months. The PR should be reviewed and approved in time, but merged right after ESLint 10.0.0 final is released.
  • In the eslint/eslint repository, submit two PRs that add "/docs/v9.x" to the skipPatterns list in docs/tools/validate-links.js. One PR should target the main branch and the other the v9.x-dev branch. The PRs should be reviewed and approved in time, but merged right before ESLint 10.0.0 is released.
  • In the eslint/eslint repository, submit a PR to update peer dependency eslint to ^10.0.0 in packages/js/package.json. The PR should be reviewed and approved in time, but merged after final ESLint v10.0.0 is released and before final @eslint/js v10.0.0 is released.
  • In the eslint/eslint repository, submit a PR to update dependency @eslint/js and peer dependency eslint to ^10.0.0 (i.e., remove prereleases from the ranges) in packages/eslint-config-eslint/package.json. The PR should be reviewed and approved in time, but merged after final ESLint v10.0.0 and final @eslint/js v10.0.0 are released.

After the Final Release

  • When possible, revert each of the temporary changes that were made during this major release cycle, like legacy-peer-deps. All changes should have already been listed in an issue.
  • When possible, update eslint plugins in packages/eslint-config-eslint/package.json to versions that support ESLint v10. When all plugins are updated, release eslint-config-eslint and update all repositories to use ESLint v10 and the new version of eslint-config-eslint for linting.

Three Months after the Final Release

  • In the eslint/eslint.org repository, submit a PR to update the text in src/_includes/partials/deprecation-notice.html to “ESLint v9.x end-of-life is (insert date here) and will not be maintained after that. Upgrade or consider long-term support options”. Update the link on “Upgrade” to point to the ESLint v10 migration guide. In the same PR, add {% include 'partials/deprecation-notice.html' %} to src/_includes/layouts/base.html, right before {{ content | safe }}. The PR should be reviewed and approved in time, but merged exactly three months after the final release.
  • In the eslint/eslint repository, submit two PRs (one should target the v9.x branch, the other should target the v9.x-dev branch) to update the text in docs/src/_includes/partials/deprecation-notice.html to “ESLint v9.x end-of-life is (insert date here) and will not be maintained after that. Upgrade or consider long-term support options”. Update the link on “Upgrade” to point to the ESLint v10 migration guide. In the same PRs, add {% include 'partials/deprecation-notice.html' %} to docs/src/_includes/layouts/base.html, right before {{ content | safe }}. The PRs should be reviewed and approved in time, but merged exactly three months after the final release.

Six Months after the Final Release

  • In the eslint/eslint.org repository, submit a PR to update the Current Release Lines table in src/content/pages/version-support.md: update v9.x Release Line column with concrete versions (e.g., v9.0.0-v9.39.2), update status to EOL, set Last Release date to the date of last released v9.x version, and update Commercial Support to HeroDevs. The PR should be reviewed and approved in time, but merged when the EOL date starts.
  • In the eslint/eslint.org repository, submit a PR to update the text in src/_includes/partials/deprecation-notice.html to “ESLint v9.x reached end-of-life on (insert date here) and is no longer maintained. Upgrade or consider long-term support options”. The PR should be reviewed and approved in time, but merged when the EOL date starts.
  • In the eslint/eslint repository, submit a PR to update the text in docs/src/_includes/partials/deprecation-notice.html to “ESLint v9.x reached end-of-life on (insert date here) and is no longer maintained. Upgrade or consider long-term support options”. The PR should target the v9.x branch (there is no need to also update the v9.x-dev branch since we will no longer be using it). The PR should be reviewed and approved in time, but merged when the EOL date starts.

Nine Months after the Final Release

  • In the eslint/eslint.org repository, submit a PR to remove {% include 'partials/deprecation-notice.html' %} from src/_includes/layouts/base.html. The PR should be reviewed and approved in time, but merged exactly nine months after the final release.

Troubleshooting

npm publish returns a 404

This typically happens due to a permission error related to the npm token.

  • release-please uses a granular access token that expires after a year. This token is tied to the eslintbot npm account and needs to be regenerated every year in March. If the access token is expired, npm publish returns a 404.
  • Jenkins uses a classic access token without an expiration date, but it does require a 2FA code to publish. If the 2FA code is incorrect, then npm publish returns a 404.
Edit this page
© OpenJS Foundation and ESLint contributors, www.openjsf.org. Content licensed under MIT License.
Change Language