typescript-eslint · JoshuaKGoldberg · May 16, 2025 · May 6, 2025 · May 6, 2025 · May 6, 2025
diff --git a/docs/maintenance/Releases.mdx b/docs/maintenance/Releases.mdx
@@ -34,6 +34,7 @@ Per [Users > Releases > Major Releases](../users/Releases.mdx#major-releases), w
        - 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.
 
 #### 1a. Shared Config Changes
@@ -77,6 +78,7 @@ These should only be done for feedback that consistently comes up in community t
    - 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.
 1. Write and share out a blog post announcing the new beta [example: [Docs: Blog post describing changes & migration strategy for v5->v6](https://github.com/typescript-eslint/typescript-eslint/issues/6466)].
    - Keep this post up-to-date as changes land in the `v${major}` branch.
+1. Send a PR to the `v${major}` branch that adds the old major version to [Users > Releases > Old Release Documentation](../users/Releases.mdx#old-release-documentation)
 1. Wait until all required PRs have been merged
 1. Write a blog post announcing the new release [example: [Docs: Release blog post for v6](https://github.com/typescript-eslint/typescript-eslint/issues/7153)], and land it in the `v${major}` branch.
 1. Let the release wait for **at least 1 week** to allow time for early adopters to help test it and discuss the changes.
@@ -93,6 +95,9 @@ They don't need any special treatment.
 1. Discuss with the maintainers to be ready for an [out-of-band](#out-of-band-releases) release. Doing this manually helps ensure someone is on-hand to action any issues that might arise from the major release.
 1. 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`](https://github.com/typescript-eslint/typescript-eslint/releases/tag/v6.0.0), [`v5.0.0`](https://github.com/typescript-eslint/typescript-eslint/releases/tag/v5.0.0)
+1. 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](../users/Releases.mdx#old-release-documentation)
 1. 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

diff --git a/docs/users/Releases.mdx b/docs/users/Releases.mdx
@@ -98,7 +98,23 @@ We assess need on a case-by-case basis though generally an emergency is defined
 
 These releases are done manually by a maintainer with the required access privileges.
 
-## Back-Porting Releases
+## Older Versions
+
+Older major versions of typescript-eslint are never maintained or supported.
+They may crash with the latest versions of TypeScript.
+Using the latest version of typescript-eslint is strongly recommended for getting the latest rule features and fixes, supporting the latest TypeScript features and syntax, and continuous performance and stability improvements.
+
+### Back-Porting Releases
 
 We **_do not_** back port releases to previously released major/minor versions.
 We only ever release forward.
+
+### Old Release Documentation
+
+You can find the last version of some older major versions under their dedicated branch deploys:
+
+- v7: [v7--typescript-eslint.netlify.app](https://v7--typescript-eslint.netlify.app)
+- v6: [v6--typescript-eslint.netlify.app](https://v6--typescript-eslint.netlify.app)
+
+Note that older documentation pages may contain outdated information and links.
+We strongly recommend using the latest version of typescript-eslint and its documentation.
diff --git a/packages/website/docusaurus.config.mts b/packages/website/docusaurus.config.mts
@@ -18,6 +18,10 @@ const remarkPlugins: MDXPlugin[] = [[npm2yarnPlugin, { sync: true }]];
 
 const githubUrl = 'https://github.com/typescript-eslint/typescript-eslint';
 
+const currentMajorVersion =
+  process.env.CURRENT_MAJOR_VERSION &&
+  Number(process.env.CURRENT_MAJOR_VERSION);
+
 const presetClassicOptions: PresetClassicOptions = {
   blog: {
     blogSidebarCount: 'ALL',
@@ -60,6 +64,26 @@ const themeConfig: AlgoliaThemeConfig & ThemeCommonConfig = {
     appId: 'N1HUB2TU6A',
     indexName: 'typescript-eslint',
   },
+  announcementBar:
+    currentMajorVersion &&
+    Number(version[0].split('.')[0]) < currentMajorVersion
+      ? {
+          content: [
+            'This documentation is for an older major version of typescript-eslint.',
+            '<br />',
+            'It is no longer maintained or supported. It may crash with the latest versions of TypeScript.',
+            '<hr />',
+            'Using the latest version of typescript-eslint is strongly recommended for',
+            'getting the latest rule features and fixes, ',
+            'supporting the latest TypeScript features and syntax, and',
+            'continuous performance and stability improvements.',
+            '<hr />',
+            'Please visit <a href="https://typescript-eslint.io">typescript-eslint.io</a> for the latest version\'s documentation.',
+          ].join('\n'),
+          id: 'old-version-announcement',
+          isCloseable: false,
+        }
+      : undefined,
   colorMode: {
     respectPrefersColorScheme: true,
   },

diff --git a/packages/website/src/css/custom.css b/packages/website/src/css/custom.css
@@ -219,3 +219,18 @@ td > p:last-child {
 h5 {
   font-weight: bold;
 }
+
+/* stylelint-disable-next-line selector-id-pattern */
+#__docusaurus > div[role='banner'] {
+  font-size: 150%;
+  height: initial;
+  position: sticky;
+  padding: 1rem 1.5rem;
+  margin: auto;
+  max-width: max(60%, 70rem);
+}
+
+/* stylelint-disable-next-line selector-id-pattern */
+#__docusaurus > div[role='banner'] a {
+  font-weight: bold;
+}