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-install-version-routing.md b/docs/exec-plans/2026-09-02-explorer-install-version-routing.md new file mode 100644 index 0000000000..de049644eb --- /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 review — PR [#7734](https://github.com/influxdata/docs-v2/pull/7734) +**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`. 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..cf657c0286 --- /dev/null +++ b/docs/exec-plans/2026-09-02-explorer-v110-release-readiness.md @@ -0,0 +1,99 @@ +# 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 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 + +- **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. +- **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. +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. + +## On release day + +Merge in this order. + +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 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 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 the new pages publish. + +3. The notification renders on its scoped paths and not on the excluded ones. + +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. 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 use a new v1.10 feature. The answer + states the version requirement and how to check it.