From b93ea29df3680956a24ecc3626e80bc13d26c316 Mon Sep 17 00:00:00 2001 From: Maria Hutt Date: Mon, 24 Aug 2026 13:17:10 -0700 Subject: [PATCH 1/4] chore(archive): add missing lint ignores and document archiving --- .prettierignore | 3 +++ CONTRIBUTING.md | 46 +++++++++++++++++++++++++++++++++++++++++----- cspell.json | 1 + vercel.json | 10 +++++++--- 4 files changed, 52 insertions(+), 8 deletions(-) diff --git a/.prettierignore b/.prettierignore index 4fc33ed30b..956f8ee3d6 100644 --- a/.prettierignore +++ b/.prettierignore @@ -27,6 +27,9 @@ versioned_docs/version-v*/reference/glossary.md # Archived versions versioned_docs/version-v5 versioned_docs/version-v6 +versioned_docs/version-v7 +static/usage/v6 +static/usage/v7 static/code/stackblitz diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 534db3dd80..ba761a7bfb 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -221,10 +221,25 @@ Archived versions are served from a frozen Vercel deployment instead of being re The archived URL has to point at a build that _included_ the version, so you build it first, then move it to `versionsArchived.json`: -1. **Build the version.** Make sure it is in `versions.json`. If you are refreshing an already-archived version, move it out of `versionsArchived.json` and back into `versions.json`. Commit, push and let Vercel deploy. -2. **Promote the deployment.** In the Vercel dashboard, open that deployment and **Promote to Production** so it does not get cleaned up. Wait for the build to finish before pushing again, or it may get canceled. -3. **Copy its URL.** Use the deployment's unique `ionic-docs--ionic1.vercel.app` URL, not the branch or production alias. -4. **Archive it.** Remove the version from `versions.json`, then add it to `versionsArchived.json` with `/docs/` appended and no trailing slash (a trailing slash causes a brief 404 flash): +1. **Add the version to the `vercel.json` redirects.** The frozen deployment serves its own copy of [`vercel.json`](./vercel.json), so a version scoped redirect has to be in place _before_ the build in the next step, or it will be missing from the archive for good. Add the version to each `:version(...)` group that applies to it. The `angular`, `react`, `vue` and `javascript` landing pages all need this, since no version ships an index page for them: + + ```json + { + "source": "/docs/:version(v6|v7|v8|v)/angular", + "destination": "/docs/:version/angular/overview" + }, + { + "source": "/docs/:version(v8|v)/javascript", + "destination": "/docs/:version/javascript/overview" + } + ``` + + The `javascript` group only goes back to v8, since v6 and v7 have no `javascript/` section. + +2. **Build the version.** Make sure it is in `versions.json`. If you are refreshing an already-archived version, move it out of `versionsArchived.json` and back into `versions.json`. Commit, push and let Vercel deploy. +3. **Promote the deployment.** In the Vercel dashboard, open that deployment and **Promote to Production** so it does not get cleaned up. Wait for the build to finish before pushing again, or it may get canceled. +4. **Copy its URL.** Use the deployment's unique `ionic-docs--ionic1.vercel.app` URL, not the branch or production alias. +5. **Archive it.** Remove the version from `versions.json`, then add it to `versionsArchived.json` with `/docs/` appended and no trailing slash (a trailing slash causes a brief 404 flash): ```json { @@ -232,7 +247,28 @@ The archived URL has to point at a build that _included_ the version, so you bui } ``` -5. **Open a PR.** Once merged, the version picker links to the archive and `main` stops building that version. +6. **Update `.prettierignore`.** Add the archived version folders to the archived versions group to keep Prettier from formatting generated files: + + ``` + static/usage/v + versioned_docs/version-v + ``` + +7. **Update `cspell.json`.** Add the archived version to the `ignorePaths` array so the spell checker skips generated files: + + ```json + "versioned_docs/version-v" + ``` + +8. **Update `renovate.json`.** Add the version's StackBlitz examples to `ignorePaths` so Renovate stops opening dependency PRs against frozen examples: + + ```json + "ignorePaths": ["static/code/stackblitz/v/**"] + ``` + + Then remove that version's `@ionic/` `allowedVersions` rule from `packageRules`, since it no longer has anything to match. + +9. **Open a PR.** Once merged, the version picker links to the archive and `main` stops building that version. Removed versions keep their `versioned_docs/` and `versioned_sidebars/` content, so they can be rebuilt anytime by adding them back to `versions.json`. diff --git a/cspell.json b/cspell.json index 57eed251d2..66681e60f7 100644 --- a/cspell.json +++ b/cspell.json @@ -20,6 +20,7 @@ "versioned_docs/**/native", "versioned_docs/version-v5", "versioned_docs/version-v6", + "versioned_docs/version-v7", "node_modules" ], "flagWords": [ diff --git a/vercel.json b/vercel.json index ea4a0e6d7d..998a5b3e6a 100644 --- a/vercel.json +++ b/vercel.json @@ -6,7 +6,7 @@ "destination": "/docs/angular/overview" }, { - "source": "/docs/:version(v6|v7)/angular", + "source": "/docs/:version(v6|v7|v8)/angular", "destination": "/docs/:version/angular/overview" }, { @@ -37,6 +37,10 @@ "source": "/docs/javascript", "destination": "/docs/javascript/overview" }, + { + "source": "/docs/:version(v8)/javascript", + "destination": "/docs/:version/javascript/overview" + }, { "source": "/docs/ja/", "destination": "/docs/ja" @@ -53,7 +57,7 @@ "destination": "/docs/react/overview" }, { - "source": "/docs/:version(v6|v7)/react", + "source": "/docs/:version(v6|v7|v8)/react", "destination": "/docs/:version/react/overview" }, { @@ -82,7 +86,7 @@ "destination": "/docs/vue/overview" }, { - "source": "/docs/:version(v6|v7)/vue", + "source": "/docs/:version(v6|v7|v8)/vue", "destination": "/docs/:version/vue/overview" }, { "source": "/docs/vue/your-first-app/2-taking-photos", "destination": "/docs/vue/your-first-app/taking-photos" }, From 1c37b51d7c0897d827d26495d767c3d4b1c6877a Mon Sep 17 00:00:00 2001 From: Maria Hutt Date: Tue, 25 Aug 2026 09:46:16 -0700 Subject: [PATCH 2/4] docs(contributing): note that versions.json excludes the current version --- CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index ba761a7bfb..cee66d0626 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -216,7 +216,7 @@ The Ionic documentation's `main` branch is deployed automatically and separately Archived versions are served from a frozen Vercel deployment instead of being rebuilt on every `main` deploy, which keeps build times and memory usage low. Two files control this: -- [`versions.json`](./versions.json): lists the versions Docusaurus rebuilds on every deploy. +- [`versions.json`](./versions.json): lists the older versions Docusaurus rebuilds on every deploy. It does not include the current version, which is built from `docs/` and takes its label from `versions.current` in `docusaurus.config.js`. - [`versionsArchived.json`](./versionsArchived.json): maps each archived version to the frozen deployment URL the version picker links to. The archived URL has to point at a build that _included_ the version, so you build it first, then move it to `versionsArchived.json`: From 9c134376c423702c7ba2a12b1640e75ec2fcfb04 Mon Sep 17 00:00:00 2001 From: Maria Hutt Date: Tue, 25 Aug 2026 10:20:31 -0700 Subject: [PATCH 3/4] docs(contributing): clarify which version needs the vercel redirects --- CONTRIBUTING.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index cee66d0626..a44544b8e0 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -214,27 +214,27 @@ The Ionic documentation's `main` branch is deployed automatically and separately ### Archiving a Version -Archived versions are served from a frozen Vercel deployment instead of being rebuilt on every `main` deploy, which keeps build times and memory usage low. Two files control this: +Archived versions are served from a frozen Vercel deployment instead of being rebuilt on every `main` deploy, which keeps build times and memory usage low. That deployment is a full snapshot of the site, so it serves every version that was in the build. Two files control this: - [`versions.json`](./versions.json): lists the older versions Docusaurus rebuilds on every deploy. It does not include the current version, which is built from `docs/` and takes its label from `versions.current` in `docusaurus.config.js`. - [`versionsArchived.json`](./versionsArchived.json): maps each archived version to the frozen deployment URL the version picker links to. The archived URL has to point at a build that _included_ the version, so you build it first, then move it to `versionsArchived.json`: -1. **Add the version to the `vercel.json` redirects.** The frozen deployment serves its own copy of [`vercel.json`](./vercel.json), so a version scoped redirect has to be in place _before_ the build in the next step, or it will be missing from the archive for good. Add the version to each `:version(...)` group that applies to it. The `angular`, `react`, `vue` and `javascript` landing pages all need this, since no version ships an index page for them: +1. **Check the `vercel.json` redirects.** Any `:version(...)` group missing a version at build time stays broken on that host for good. Add the version that most recently stopped being current, since it is the one most likely to be missing. The `angular`, `react`, `vue` and `javascript` landing pages each need a group, as no version ships an index page for them: ```json { - "source": "/docs/:version(v6|v7|v8|v)/angular", + "source": "/docs/:version(v6|v7|v)/angular", "destination": "/docs/:version/angular/overview" }, { - "source": "/docs/:version(v8|v)/javascript", + "source": "/docs/:version(v)/javascript", "destination": "/docs/:version/javascript/overview" } ``` - The `javascript` group only goes back to v8, since v6 and v7 have no `javascript/` section. + The `javascript` group only covers versions that have a `javascript/` section. 2. **Build the version.** Make sure it is in `versions.json`. If you are refreshing an already-archived version, move it out of `versionsArchived.json` and back into `versions.json`. Commit, push and let Vercel deploy. 3. **Promote the deployment.** In the Vercel dashboard, open that deployment and **Promote to Production** so it does not get cleaned up. Wait for the build to finish before pushing again, or it may get canceled. From 7e34b4a482b8a45c923177a4b6c13b4fefdf7ba8 Mon Sep 17 00:00:00 2001 From: Maria Hutt Date: Tue, 25 Aug 2026 15:33:44 -0700 Subject: [PATCH 4/4] docs(contributing): update archived section Co-authored-by: Brandy Smith <6577830+brandyscarney@users.noreply.github.com> --- CONTRIBUTING.md | 63 ++++++++++++++++++++++++++++++++++++------------- 1 file changed, 47 insertions(+), 16 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index a44544b8e0..24dc310f71 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -219,56 +219,87 @@ Archived versions are served from a frozen Vercel deployment instead of being re - [`versions.json`](./versions.json): lists the older versions Docusaurus rebuilds on every deploy. It does not include the current version, which is built from `docs/` and takes its label from `versions.current` in `docusaurus.config.js`. - [`versionsArchived.json`](./versionsArchived.json): maps each archived version to the frozen deployment URL the version picker links to. -The archived URL has to point at a build that _included_ the version, so you build it first, then move it to `versionsArchived.json`: +The docs keep the current version plus one older version rebuildable, so each major release archives one version and involves two different version numbers. The steps below refer to them as: -1. **Check the `vercel.json` redirects.** Any `:version(...)` group missing a version at build time stays broken on that host for good. Add the version that most recently stopped being current, since it is the one most likely to be missing. The `angular`, `react`, `vue` and `javascript` landing pages each need a group, as no version ships an index page for them: +- ``: the version being frozen and removed from `versions.json`. +- ``: the version that just stopped being current and moved into `versions.json`. It is not being archived, but step 1 has to account for it. + +For example, when `v9` becomes current: `v8` is `` and `v7` is ``. + +The archived URL has to point at a build that _included_ ``, so you build it first, then move it to `versionsArchived.json`: + +1. **Check the `vercel.json` redirects.** The frozen deployment bakes in whatever `vercel.json` looked like at build time, and it serves every version in that build. Any `:version(...)` group missing a version therefore stays broken on that host for good. Make sure the groups already list ``, which is the one most likely to be missing since it only just moved into `versions.json`. The `angular`, `react`, `vue` and `javascript` landing pages each need a group, as no version ships an index page for them: ```json { - "source": "/docs/:version(v6|v7|v)/angular", + "source": "/docs/:version(v6|v7|)/angular", "destination": "/docs/:version/angular/overview" }, { - "source": "/docs/:version(v)/javascript", + "source": "/docs/:version()/javascript", "destination": "/docs/:version/javascript/overview" } ``` - The `javascript` group only covers versions that have a `javascript/` section. + The groups accumulate, so existing entries stay in place whether or not that version is archived and you are only ever adding to them. The `javascript` group only covers versions that have a `javascript/` section. -2. **Build the version.** Make sure it is in `versions.json`. If you are refreshing an already-archived version, move it out of `versionsArchived.json` and back into `versions.json`. Commit, push and let Vercel deploy. +Everything from here on refers to ``: + +2. **Build ``.** Make sure it is in `versions.json`. If you are refreshing an already-archived version, move it out of `versionsArchived.json` and back into `versions.json`. Commit, push and let Vercel deploy. 3. **Promote the deployment.** In the Vercel dashboard, open that deployment and **Promote to Production** so it does not get cleaned up. Wait for the build to finish before pushing again, or it may get canceled. 4. **Copy its URL.** Use the deployment's unique `ionic-docs--ionic1.vercel.app` URL, not the branch or production alias. -5. **Archive it.** Remove the version from `versions.json`, then add it to `versionsArchived.json` with `/docs/` appended and no trailing slash (a trailing slash causes a brief 404 flash): +5. **Archive it.** Remove `` from `versions.json`, then add it to `versionsArchived.json` with `/docs/` appended and no trailing slash (a trailing slash causes a brief 404 flash): + + _`versions.json`_ + + ```diff + [ + - "v8", + - "" + + "v8" + ] + ``` + + _`versionsArchived.json`_ ```json { - "v6": "https://ionic-docs--ionic1.vercel.app/docs/v6" + "": "https://ionic-docs--ionic1.vercel.app/docs/", + "v6": "https://ionic-docs-lq0if04rc-ionic1.vercel.app/docs/v6", + "v5": "https://ionic-docs-5utg8ms4c-ionic1.vercel.app/docs/v5" } ``` 6. **Update `.prettierignore`.** Add the archived version folders to the archived versions group to keep Prettier from formatting generated files: ``` - static/usage/v - versioned_docs/version-v + static/usage/ + versioned_docs/version- ``` 7. **Update `cspell.json`.** Add the archived version to the `ignorePaths` array so the spell checker skips generated files: - ```json - "versioned_docs/version-v" + ```diff + "ignorePaths": [ + ... + "versioned_docs/version-v5", + "versioned_docs/version-v6", + + "versioned_docs/version-" + ] ``` -8. **Update `renovate.json`.** Add the version's StackBlitz examples to `ignorePaths` so Renovate stops opening dependency PRs against frozen examples: +8. **Update `renovate.json`.** Add the archived version's StackBlitz examples to `ignorePaths` so Renovate stops opening dependency PRs against frozen examples: - ```json - "ignorePaths": ["static/code/stackblitz/v/**"] + ```diff + "ignorePaths": [ + "static/code/stackblitz/v6/**", + + "static/code/stackblitz//**" + ] ``` Then remove that version's `@ionic/` `allowedVersions` rule from `packageRules`, since it no longer has anything to match. -9. **Open a PR.** Once merged, the version picker links to the archive and `main` stops building that version. +9. **Open a PR.** Once merged, the version picker links to the archive and `main` stops building ``. Removed versions keep their `versioned_docs/` and `versioned_sidebars/` content, so they can be rebuilt anytime by adding them back to `versions.json`.