From bbfd270dd39c6d1ac1eeed90c055273056f49d04 Mon Sep 17 00:00:00 2001 From: Jason Stirnaman Date: Wed, 2 Sep 2026 12:57:34 -0500 Subject: [PATCH 1/4] docs(explorer): add exec-plan for install version routing What changed: Adds docs/exec-plans/2026-09-02-explorer-install-version-routing.md, the decision record for restructuring the InfluxDB 3 Explorer install documentation ahead of the v1.10 release. Why: Explorer v1.9 is the last release distributed as a standalone Docker container. Starting with v1.10, Explorer is included with InfluxDB 3 Enterprise and deployed as WebAssembly (WASM). The current pages state no version or edition scope, so readers, search engines, retrieval systems, and coding agents all get Docker as the unconditional answer to "how do I install Explorer". Impact: Documentation only. No content or template changes in this commit. The record fixes the approach before implementation: keep the /influxdb3/explorer/install/ URL as a version-routing hub, move the Docker body to a child page that declares its version ceiling, and use existing frontmatter (metadata, cascade.prepend) instead of new template logic. Verification: None required for this commit. The exec-plan lists the verification steps for the implementation that follows. Claude-Session: https://claude.ai/code/session_01DZg2nkJ1rSRVqp2R9hZZh7 --- ...-09-02-explorer-install-version-routing.md | 128 ++++++++++++++++++ 1 file changed, 128 insertions(+) create mode 100644 docs/exec-plans/2026-09-02-explorer-install-version-routing.md diff --git a/docs/exec-plans/2026-09-02-explorer-install-version-routing.md b/docs/exec-plans/2026-09-02-explorer-install-version-routing.md new file mode 100644 index 0000000000..f4955e086a --- /dev/null +++ b/docs/exec-plans/2026-09-02-explorer-install-version-routing.md @@ -0,0 +1,128 @@ +# Explorer install docs: route by version and edition + +**Status:** In progress — branch `explorer-v1.10-install-restructure` +**Closes:** [#6702](https://github.com/influxdata/docs-v2/issues/6702) + +## Goal + +Restructure the InfluxDB 3 Explorer install documentation so that each page +states which Explorer versions and which InfluxDB 3 editions it applies to. +After this change, `/influxdb3/explorer/install/` routes readers by version +instead of presenting Docker as the only deployment method, and the Docker +instructions live on a child page that declares its version ceiling in +frontmatter, in the lede, and in the Markdown twin. + +## Why now + +Explorer v1.9 is the last release distributed as a standalone Docker container. +Starting with v1.10, Explorer is included with InfluxDB 3 Enterprise and is +deployed as WebAssembly (WASM). The current pages have no version or edition +scoping: + +- `content/influxdb3/explorer/install.md` documents only Docker. +- `content/influxdb3/explorer/_index.md` repeats a `docker pull` quick start. +- `content/influxdb3/explorer/about/_index.md` states full Core and Enterprise + support with no end version. +- `data/products.yml` lists `Docker` in `schema.operating_system`, which feeds + the JSON-LD `SoftwareApplication` node. + +Each of these tells readers, search engines, retrieval systems, and coding +agents that Explorer is a Docker container that works with Core. Doing the +restructure before v1.10 ships means the corpus and search index carry the +version scoping before the release changes the answer. + +Issue #6702 reports the related gap: the docs never state outright which +distributions exist, so a docs-grounded assistant can only infer the +limitation. + +## Decisions + +- **Keep `/influxdb3/explorer/install/` as the URL and convert it to a + version-routing hub.** The URL holds the search ranking, seven inbound + in-repo links (three of them deep anchors), the `llms.txt` corpus entry, and + any existing model memory. Moving the page under `/get-started/` or demoting + it in the navigation would break those without addressing the actual problem, + which is the page content, not its address. +- **Move the Docker body to `install/docker.md` unchanged.** Keeping the body + intact preserves the three anchors that other pages link to: + `#choose-operational-mode`, `#network-exposure-and-access-control`, and + `#set-file-permissions-for-upgrades`. +- **Do not redirect `/install/` to `/install/docker/`.** A redirect would send + every "install Explorer" search result and every agent's first URL guess to + the deprecated path. +- **Use `metadata: [Explorer v1.9 and earlier]` rather than + `introduced`/`deprecated`.** Both render into the `ul.metadata` list under the + h1 and into the first line of the Markdown twin, verified against + `/influxdb3/clustered/reference/cli/influxctl/query/index.md` (`* influxctl + 2.4.0+`) and `/telegraf/v1/input-plugins/jenkins/index.md` (`* Telegraf + v1.9.0+`). The `introduced`/`deprecated` pair renders as a range + ("v1.0.0 – v1.10.0"), which is ambiguous about the last working release. + `metadata` states the ceiling exactly. +- **Keep the Docker page published and indexed.** Explorer v1.9 remains + supported, and removing or hiding the instructions creates a retrieval dead + end. A page that states its own version ceiling is not misleading. +- **Use `cascade.prepend` on `explorer/_index.md` for the transition notice, + not a template banner.** `article/stable-version.html` is gated on a + hardcoded product whitelist and a `/vN/` URL segment, neither of which + applies to Explorer, and extending it would add magic values to a template + (see `.claude/rules/layouts.md`). `article/special-state.html` has the same + problem. `cascade.prepend` is documented in `DOCS-FRONTMATTER.md` and needs no + template change. +- **Accept the twin cost of the cascaded notice, and remove it after v1.11.** + Prepended content appears in every Explorer Markdown twin and in + `llms-full.txt`, which makes the first chunk of all 12 Explorer pages more + alike (the twin-hygiene problem tracked in + [#7323](https://github.com/influxdata/docs-v2/issues/7323)). The notice is + three lines and is worth that cost while the transition is live. +- **Document version verification with `GET /ping`, not only + `influxdb3 --version`.** WASM availability depends on the InfluxDB 3 server + version and build, not on Explorer alone. `GET /ping` returns + `x-influxdb-version` and `x-influxdb-build` (`Core` or `Enterprise`) in + headers and `version` in the body + (`api-docs/influxdb3/enterprise/influxdb3-enterprise-openapi.yaml`), so one + command answers both questions and works headlessly against a remote + instance. A `HEAD` request returns 404, so the docs specify `GET`. + +## Explicitly out of scope + +- WASM deployment instructions under `/influxdb3/enterprise/`. Those wait until + v1.10 ships; this change only prepares the routing and cross-links. +- `data/products.yml` updates to `latest_patch` and `schema.operating_system`. + Both change on release day, not before. +- The `localhost` connection failure reported in + [#7333](https://github.com/influxdata/docs-v2/issues/7333). It affects the + Docker instructions but is a separate content fix. +- Extending `article/stable-version.html` to support products without a `/vN/` + URL segment. + +## How to update + +The Explorer version ceiling appears in four places on +`content/influxdb3/explorer/install/docker.md`: the `metadata` frontmatter, the +`description` frontmatter, the lede, and the transition notice cascaded from +`content/influxdb3/explorer/_index.md`. Update the notice in `_index.md` once +and it changes on every Explorer page. Remove the `cascade.prepend` block when +v1.11 ships. + +## Verification + +1. `npx hugo --quiet` builds without errors. +2. Confirm the three anchors still resolve within `install/docker/`, and that no + in-repo link points at `/influxdb3/explorer/install/#` for a Docker-only + section. +3. `yarn check:md-coherence` confirms the head link, `sitemap-md.xml`, and + corpus surfaces agree after the URL structure changes. +4. Run the Cypress navigation tests. Converting a single page to a section + changes the menu tree. +5. After deploy, check the published Markdown twins. PR previews return 404 for + twins, so use production or staging: + + ```sh + curl -s --compressed https://docs.influxdata.com/influxdb3/explorer/install/index.md | head -20 + curl -s --compressed https://docs.influxdata.com/influxdb3/explorer/install/docker/index.md | head -20 + ``` + + The Docker twin starts with `* Explorer v1.9 and earlier` above the lede. +6. Ask the documentation MCP server "How do I install InfluxDB 3 Explorer?" + after the corpus rebuilds. The answer routes by version instead of returning + `docker run`. From 512f783583fb31b6058d055e7c2c4cf63394e75b Mon Sep 17 00:00:00 2001 From: Jason Stirnaman Date: Wed, 2 Sep 2026 12:58:18 -0500 Subject: [PATCH 2/4] docs(explorer): link PR in exec-plan status Claude-Session: https://claude.ai/code/session_01DZg2nkJ1rSRVqp2R9hZZh7 --- docs/exec-plans/2026-09-02-explorer-install-version-routing.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/exec-plans/2026-09-02-explorer-install-version-routing.md b/docs/exec-plans/2026-09-02-explorer-install-version-routing.md index f4955e086a..de049644eb 100644 --- a/docs/exec-plans/2026-09-02-explorer-install-version-routing.md +++ b/docs/exec-plans/2026-09-02-explorer-install-version-routing.md @@ -1,6 +1,6 @@ # Explorer install docs: route by version and edition -**Status:** In progress — branch `explorer-v1.10-install-restructure` +**Status:** In review — PR [#7734](https://github.com/influxdata/docs-v2/pull/7734) **Closes:** [#6702](https://github.com/influxdata/docs-v2/issues/6702) ## Goal From 441d4e2c4ca5a2d4250df0ecfd1484faabc24ecd Mon Sep 17 00:00:00 2001 From: Jason Stirnaman Date: Wed, 2 Sep 2026 13:29:52 -0500 Subject: [PATCH 3/4] docs(explorer): add version availability conventions and release readiness plan What changed: - Adds DOCS-VERSION-AVAILABILITY.md, which documents how to state a version or edition constraint: which marker to use for page-wide versus section-level scope, which surface carries which fact, where a page lives when a feature spans two products, the version-check pattern, and how temporary notices are retired. - Adds docs/exec-plans/2026-09-02-explorer-v110-release-readiness.md, the ordered pre-release, release-day, and post-release task sequence for the Explorer v1.10 and InfluxDB 3 Enterprise release. - Lists the new reference in AGENTS.md and regenerates the instruction adapters. Why: The install restructure exec-plan prepares version routing but leaves the WASM instructions, products.yml updates, and hub lede flip until v1.10 ships. The release sequence needs to exist before release day. The conventions are feature-agnostic and apply to any version-gated documentation, so they belong in a durable reference rather than in a per-release plan. Impact: Documentation for contributors and agents. No published content changes. The conventions reference links to DOCS-FRONTMATTER.md and DOCS-AI-VISIBILITY.md instead of restating field syntax or artifact layers. It records that data/notifications.yaml renders in the footer and therefore never reaches Markdown twins or llms-full.txt, so a version fact stated only in a notification is invisible to AI consumers. Verification: yarn build:agent:instructions and yarn validate:agent-instructions both pass. Markdown lint passes on the new files. Claude-Session: https://claude.ai/code/session_01DZg2nkJ1rSRVqp2R9hZZh7 --- DOCS-VERSION-AVAILABILITY.md | 107 ++++++++++++++++ ...6-09-02-explorer-v110-release-readiness.md | 118 ++++++++++++++++++ 2 files changed, 225 insertions(+) create mode 100644 DOCS-VERSION-AVAILABILITY.md create mode 100644 docs/exec-plans/2026-09-02-explorer-v110-release-readiness.md diff --git a/DOCS-VERSION-AVAILABILITY.md b/DOCS-VERSION-AVAILABILITY.md new file mode 100644 index 0000000000..a7ef6f7411 --- /dev/null +++ b/DOCS-VERSION-AVAILABILITY.md @@ -0,0 +1,107 @@ +# Documenting version availability + +How to state which product versions and editions a page or feature applies to. + +This page covers the decisions: which marker to use, which surface carries +which fact, where a page lives, and when a notice is removed. +For field syntax, see [DOCS-FRONTMATTER.md](DOCS-FRONTMATTER.md). +For how Markdown twins and corpora are published, see +[DOCS-AI-VISIBILITY.md](DOCS-AI-VISIBILITY.md). + +## Choose a marker + +Match the marker to the scope of the version constraint. + +| Scope | Use | Example | +| ---------------------------------------------------------- | ------------------------------------------------- | -------------------------------------------- | +| The whole page applies to a version range | `metadata:` frontmatter | `metadata: [Explorer v1.9 and earlier]` | +| The whole page is one of a generated set with a real range | `introduced`, `deprecated`, `removed` frontmatter | `introduced: "v1.9.0"` | +| One section applies to a version range | Heading attribute | `## Configure user auth {metadata="v1.10+"}` | + +Use `metadata:` when you need to state a ceiling or an exact phrase. +The `introduced`/`deprecated`/`removed` fields render as a range, such as +"InfluxDB 3 Explorer v1.0.0 – v1.10.0", which doesn't say which release is the +last working one. +Telegraf plugin pages use the range fields because the values are generated +from plugin metadata. + +Don't state a version constraint only in body text. +Frontmatter markers render in a list under the page h1 and appear above the +lede in the page's Markdown twin, which is the text a retrieval system reads +first. + +## Choose a surface + +Each surface reaches a different audience. +Decide which one carries the fact before you write it. + +| Surface | Reaches | Use for | +| ------------------------------------------------- | -------------------------------------------------------- | ----------------------------------------------------------------------- | +| Frontmatter markers and the lede | Readers, search engines, Markdown twins, `llms-full.txt` | Any version or edition fact a reader or an agent needs to act correctly | +| `prepend` / `append` frontmatter (with `cascade`) | Same as above, on every page it cascades to | A transition notice that must appear in the twin | +| `data/notifications.yaml` | Readers only | A dated announcement, such as a release or a scheduled change | + +Notifications render in the site footer through +`layouts/partials/footer/notifications.html`, outside the article element. +They don't appear in Markdown twins or in `llms-full.txt`. +A fact that exists only in a notification is invisible to every AI consumer of +the docs, so don't use a notification as the only statement of a version +requirement. + +Cascaded `prepend` content appears in the twin of every page it reaches, which +makes the first chunk of those pages similar to each other. +Keep cascaded notices to a few lines, and remove them when the transition ends. + +## Place a feature page + +When a feature spans two products, such as a UI feature that depends on a +server capability: + +1. Put the canonical page in the product that owns the behavior. +2. Add `alt_links` so the product switcher moves readers to the equivalent page + in the other product. +3. Add `related` entries from the other product's page. + +Don't duplicate the instructions in both products. +If both products need the same body, use `source:` to share the content and set +`canonical: self` on the page whose URL marks the product identity. + +## Include a version check + +A page that documents a version-gated feature states how to verify the version, +or links to a page that does. +Give both a local check and a check that works against a running instance, so +that a reader without shell access to the server can still confirm the version. + +Local: + +```bash +influxdb3 --version +``` + +Running instance: + +```sh +curl --get "http://localhost:8181/ping" \ + --header "Authorization: Bearer AUTH_TOKEN" +``` + +The `/ping` response includes the `x-influxdb-version` and `x-influxdb-build` +headers, and `version` and `revision` in the body. +Because `x-influxdb-build` reports `Core` or `Enterprise`, `/ping` is the only +check that answers both the version question and the edition question. +Use `GET`; a `HEAD` request returns `404`. + +## Retire a notice + +Every temporary notice names the release that removes it. + +- For a `cascade.prepend` notice, record the removal release in the exec-plan + for the change that added it. +- For a `data/notifications.yaml` entry, record the removal release with the + entry `id`, so the entry can be found and deleted without reading the message + text. + +Version markers in frontmatter are permanent. +They describe a fact about the release, not a temporary state, so leave them in +place after the transition ends. diff --git a/docs/exec-plans/2026-09-02-explorer-v110-release-readiness.md b/docs/exec-plans/2026-09-02-explorer-v110-release-readiness.md new file mode 100644 index 0000000000..a32b5bb397 --- /dev/null +++ b/docs/exec-plans/2026-09-02-explorer-v110-release-readiness.md @@ -0,0 +1,118 @@ +# Explorer v1.10 release readiness + +**Status:** In progress — PR [#7734](https://github.com/influxdata/docs-v2/pull/7734) +**Refs:** [2026-09-02-explorer-install-version-routing.md](2026-09-02-explorer-install-version-routing.md) + +## Goal + +Define the documentation work to complete before and on the day InfluxDB 3 +Explorer v1.10 and the accompanying InfluxDB 3 Enterprise release ship. +The sequence applies regardless of which features the release contains. +Feature-specific content, such as user authorization, follows the same steps. + +## Why now + +The install restructure in the referenced exec-plan prepares the version +routing but stops short of the release itself. It deliberately leaves the WASM +deployment instructions, the `data/products.yml` updates, and the hub lede flip +until v1.10 ships. This plan records that remaining work as an ordered sequence +so the release day doesn't depend on someone reconstructing it. + +The conventions the release work follows are documented separately in +[DOCS-VERSION-AVAILABILITY.md](../../DOCS-VERSION-AVAILABILITY.md), which this +plan applies rather than restates. + +## Decisions + +- **Feature pages are drafted before the release, not written on the day.** + Each new page carries its version metadata, its version-verification step, + and its cross-product links from the first commit. Publishing then becomes a + frontmatter change rather than an authoring task. +- **Use `data/notifications.yaml` for the release announcement, and keep the + version facts in the pages.** Notifications render in the footer, outside the + article, so they don't appear in Markdown twins or `llms-full.txt`. The + announcement is for readers; the version scope that agents and retrieval + systems need stays in frontmatter and the lede. +- **Add the notification as a commented-out stub before the release.** The + `influxdb3-cloud-ga` entry in `data/notifications.yaml` already uses this + pattern: a commented block with a checklist of what to confirm before it goes + live. Uncommenting is a one-line release-day action. +- **Order the release-day steps so no published page contradicts another at any + point.** Feature pages publish first, then the hub lede flips to lead with + WASM, then `data/products.yml` changes. Reversing that order leaves the hub + pointing at unpublished pages. +- **Retire notices by identifier, not by search.** The `cascade.prepend` + transition notice and the notification entry are both removed at v1.11, and + both are named here so the removal doesn't depend on finding them again. +- **The install restructure exec-plan stays as written.** This plan follows it. + Where the two describe the same file, the restructure plan describes the + pre-release state and this plan describes the release-day change. + +## Pre-release tasks + +1. Draft each new feature page with `draft: true`. + Apply the version marker for the feature's availability, per + [DOCS-VERSION-AVAILABILITY.md](../../DOCS-VERSION-AVAILABILITY.md). + Use a page-level `metadata:` entry when the whole page is new in v1.10, and + a heading attribute such as `{metadata="v1.10+"}` when only a section is. +2. Include the version-check step on each feature page, or link to the section + of the install hub that documents it. +3. Add `alt_links` in both directions between the Explorer page and the + InfluxDB 3 Enterprise page that documents the server side of the feature. +4. Add the WASM deployment instructions to the InfluxDB 3 Enterprise section, + including the server version that introduced them. +5. Add a commented-out entry to `data/notifications.yaml` with the final `id`, + `scope`, `title`, and `slug`, and a comment listing what to confirm before + uncommenting. +6. Draft the release notes entry in + `content/influxdb3/explorer/release-notes/_index.md`. + +## Release-day tasks + +Complete in this order. + +1. Remove `draft: true` from the feature pages. +2. Update the install hub lede at + `content/influxdb3/explorer/install/_index.md` so the WASM path is described + first and Docker reads as the path for v1.9 and earlier. +3. Update `data/products.yml`: set `latest_patch` to the new Explorer version, + and update `schema.operating_system`, which currently lists `Docker` and + feeds the JSON-LD `SoftwareApplication` node. +4. Publish the release notes entry. +5. Uncomment the `data/notifications.yaml` entry. +6. Verify the published surfaces (see Verification). + +## Post-release tasks + +At the v1.11 release: + +1. Delete the `data/notifications.yaml` entry by `id`. +2. Remove the `cascade.prepend` transition notice from + `content/influxdb3/explorer/_index.md`. +3. Leave all frontmatter version markers in place. They state a fact about the + release, not a temporary condition. + +## Verification + +1. `npx hugo --quiet` builds without errors. + +2. `yarn check:md-coherence` confirms the head links, `sitemap-md.xml`, and + corpus surfaces agree after pages are published. + +3. Confirm the notification renders on the scoped paths and doesn't render on + the excluded ones. + +4. After deploy, confirm the version marker leads each new page's Markdown + twin. PR previews return 404 for twins, so use production or staging: + + ```sh + curl -s --compressed https://docs.influxdata.com/influxdb3/explorer//index.md | head -20 + ``` + +5. Confirm the notification text doesn't appear in the twin or in + `https://docs.influxdata.com/influxdb3/explorer/llms-full.txt`. Notifications + are footer content; if the text appears in either file, it was added to the + wrong surface. + +6. Ask the documentation MCP server how to install Explorer and how to use the + new feature. Both answers state the version requirement. From c103ba91167bf68576dbcc413aed6d01c0dc0e75 Mon Sep 17 00:00:00 2001 From: Jason Stirnaman Date: Wed, 2 Sep 2026 14:01:25 -0500 Subject: [PATCH 4/4] docs(explorer): tighten release readiness plan What changed: Slims the release readiness exec-plan to the v1.10 release. Adds the decision that every new feature page shows the reader how to check whether their version has the feature, covering both the Explorer version and the InfluxDB 3 server version and edition. Replaces the draft:true default with merging at release, keeping draft:true for specific cases such as a link target other merged content needs. Why: The first draft stated version markers but not how a reader arriving from search determines which version they're running, and it assumed a publishing workflow the team doesn't use. Impact: Planning document only. Verification: Markdown lint passes. Claude-Session: https://claude.ai/code/session_01DZg2nkJ1rSRVqp2R9hZZh7 --- ...6-09-02-explorer-v110-release-readiness.md | 139 ++++++++---------- 1 file changed, 60 insertions(+), 79 deletions(-) diff --git a/docs/exec-plans/2026-09-02-explorer-v110-release-readiness.md b/docs/exec-plans/2026-09-02-explorer-v110-release-readiness.md index a32b5bb397..cf657c0286 100644 --- a/docs/exec-plans/2026-09-02-explorer-v110-release-readiness.md +++ b/docs/exec-plans/2026-09-02-explorer-v110-release-readiness.md @@ -5,114 +5,95 @@ ## Goal -Define the documentation work to complete before and on the day InfluxDB 3 -Explorer v1.10 and the accompanying InfluxDB 3 Enterprise release ship. -The sequence applies regardless of which features the release contains. -Feature-specific content, such as user authorization, follows the same steps. - -## Why now - -The install restructure in the referenced exec-plan prepares the version -routing but stops short of the release itself. It deliberately leaves the WASM -deployment instructions, the `data/products.yml` updates, and the hub lede flip -until v1.10 ships. This plan records that remaining work as an ordered sequence -so the release day doesn't depend on someone reconstructing it. - -The conventions the release work follows are documented separately in -[DOCS-VERSION-AVAILABILITY.md](../../DOCS-VERSION-AVAILABILITY.md), which this -plan applies rather than restates. +Define the documentation work for the InfluxDB 3 Explorer v1.10 release and the +InfluxDB 3 Enterprise release that carries it. The install restructure prepares +the version routing; this plan covers what changes when v1.10 ships. ## Decisions -- **Feature pages are drafted before the release, not written on the day.** - Each new page carries its version metadata, its version-verification step, - and its cross-product links from the first commit. Publishing then becomes a - frontmatter change rather than an authoring task. +- **Every new feature page tells the reader how to check whether their version + has the feature.** A version marker states the requirement, but a reader + arriving from search doesn't know which version they're running. Each feature + page states the requirement and shows the check, or links to the check in the + install hub. See + [DOCS-VERSION-AVAILABILITY.md](../../DOCS-VERSION-AVAILABILITY.md). +- **The check covers both the Explorer version and the InfluxDB 3 server + version and edition.** A v1.10 feature can require both. `GET /ping` returns + `x-influxdb-version` and `x-influxdb-build` (`Core` or `Enterprise`), so it + answers the server half in one request, including against a remote instance. +- **Merge at release rather than publishing with `draft: true`.** Content pages + merge on release day. Use `draft: true` only when a page must exist in the + branch before the release for a specific reason, such as a link target that + other merged content depends on. - **Use `data/notifications.yaml` for the release announcement, and keep the version facts in the pages.** Notifications render in the footer, outside the article, so they don't appear in Markdown twins or `llms-full.txt`. The announcement is for readers; the version scope that agents and retrieval systems need stays in frontmatter and the lede. -- **Add the notification as a commented-out stub before the release.** The - `influxdb3-cloud-ga` entry in `data/notifications.yaml` already uses this - pattern: a commented block with a checklist of what to confirm before it goes - live. Uncommenting is a one-line release-day action. -- **Order the release-day steps so no published page contradicts another at any - point.** Feature pages publish first, then the hub lede flips to lead with - WASM, then `data/products.yml` changes. Reversing that order leaves the hub - pointing at unpublished pages. -- **Retire notices by identifier, not by search.** The `cascade.prepend` - transition notice and the notification entry are both removed at v1.11, and - both are named here so the removal doesn't depend on finding them again. -- **The install restructure exec-plan stays as written.** This plan follows it. - Where the two describe the same file, the restructure plan describes the - pre-release state and this plan describes the release-day change. - -## Pre-release tasks - -1. Draft each new feature page with `draft: true`. - Apply the version marker for the feature's availability, per - [DOCS-VERSION-AVAILABILITY.md](../../DOCS-VERSION-AVAILABILITY.md). - Use a page-level `metadata:` entry when the whole page is new in v1.10, and - a heading attribute such as `{metadata="v1.10+"}` when only a section is. -2. Include the version-check step on each feature page, or link to the section - of the install hub that documents it. -3. Add `alt_links` in both directions between the Explorer page and the - InfluxDB 3 Enterprise page that documents the server side of the feature. -4. Add the WASM deployment instructions to the InfluxDB 3 Enterprise section, +- **Order the release-day merge so no published page points at an unpublished + one.** Feature pages first, then the install hub lede, then + `data/products.yml`. + +## Before the release + +1. Write each new feature page with its version marker: page-level `metadata:` + when the whole page is new in v1.10, a `{metadata="v1.10+"}` heading + attribute when only a section is. +2. Add the version check to each feature page. State the Explorer version the + feature requires and, when the feature depends on the server, the InfluxDB 3 + version and edition. Show the `/ping` request or link to the check in the + install hub. +3. Add the WASM deployment instructions to the InfluxDB 3 Enterprise section, including the server version that introduced them. -5. Add a commented-out entry to `data/notifications.yaml` with the final `id`, - `scope`, `title`, and `slug`, and a comment listing what to confirm before - uncommenting. -6. Draft the release notes entry in +4. Add `alt_links` in both directions between each Explorer feature page and + the Enterprise page that documents the server side. +5. Write the release notes entry in `content/influxdb3/explorer/release-notes/_index.md`. +6. Add a commented-out `data/notifications.yaml` entry with the final `id`, + `scope`, `title`, and `slug`, following the `influxdb3-cloud-ga` stub + already in that file. -## Release-day tasks - -Complete in this order. +## On release day -1. Remove `draft: true` from the feature pages. -2. Update the install hub lede at - `content/influxdb3/explorer/install/_index.md` so the WASM path is described - first and Docker reads as the path for v1.9 and earlier. -3. Update `data/products.yml`: set `latest_patch` to the new Explorer version, - and update `schema.operating_system`, which currently lists `Docker` and - feeds the JSON-LD `SoftwareApplication` node. -4. Publish the release notes entry. -5. Uncomment the `data/notifications.yaml` entry. -6. Verify the published surfaces (see Verification). +Merge in this order. -## Post-release tasks +1. Feature pages and the Enterprise WASM deployment page. +2. The install hub lede at `content/influxdb3/explorer/install/_index.md`, so + the WASM path is described first and Docker reads as the path for v1.9 and + earlier. +3. `data/products.yml`: set `latest_patch` to the new Explorer version and + update `schema.operating_system`, which lists `Docker` and feeds the JSON-LD + `SoftwareApplication` node. +4. The release notes entry. +5. The `data/notifications.yaml` entry, uncommented. -At the v1.11 release: +## At v1.11 1. Delete the `data/notifications.yaml` entry by `id`. 2. Remove the `cascade.prepend` transition notice from `content/influxdb3/explorer/_index.md`. -3. Leave all frontmatter version markers in place. They state a fact about the - release, not a temporary condition. +3. Leave the frontmatter version markers. They state a fact about the release, + not a temporary condition. ## Verification 1. `npx hugo --quiet` builds without errors. 2. `yarn check:md-coherence` confirms the head links, `sitemap-md.xml`, and - corpus surfaces agree after pages are published. + corpus surfaces agree after the new pages publish. -3. Confirm the notification renders on the scoped paths and doesn't render on - the excluded ones. +3. The notification renders on its scoped paths and not on the excluded ones. -4. After deploy, confirm the version marker leads each new page's Markdown - twin. PR previews return 404 for twins, so use production or staging: +4. After deploy, the version marker leads each new page's Markdown twin. PR + previews return 404 for twins, so use production or staging: ```sh curl -s --compressed https://docs.influxdata.com/influxdb3/explorer//index.md | head -20 ``` -5. Confirm the notification text doesn't appear in the twin or in - `https://docs.influxdata.com/influxdb3/explorer/llms-full.txt`. Notifications - are footer content; if the text appears in either file, it was added to the - wrong surface. +5. The notification text appears in neither the twins nor + `https://docs.influxdata.com/influxdb3/explorer/llms-full.txt`. If it does, + it was added to the wrong surface. -6. Ask the documentation MCP server how to install Explorer and how to use the - new feature. Both answers state the version requirement. +6. Ask the documentation MCP server how to use a new v1.10 feature. The answer + states the version requirement and how to check it.