docs(v1): share byte-identical v1 content between OSS and Enterprise - #7622
Draft
jstirnaman wants to merge 5 commits into
Draft
docs(v1): share byte-identical v1 content between OSS and Enterprise#7622jstirnaman wants to merge 5 commits into
jstirnaman wants to merge 5 commits into
Conversation
InfluxDB v1 OSS (content/influxdb/v1) and v1 Enterprise (content/enterprise_influxdb/v1) kept two copies of every overlapping page, coupled by convention only. They drifted: 74 overlapping pages differ by 4,881 lines, including edition-independent Flux guides and OSS links to a tools/shell/ page that no longer exists. Move the 31 pages whose two copies are provably equivalent into content/shared/influxdb-v1/, leaving thin front-matter stubs. For these, duplication is now structurally impossible rather than discouraged. The v1 pair is the only shared pair whose editions do not share a product root, so the existing <product-root>/version link placeholder cannot serve it. Shared v1 content uses a neutral /product/version/ placeholder that article/content.html resolves from the consuming page's content_path in data/products.yml. Path resolution no longer parses the URL. Both v1 editions cascade version: v1, so show-in/hide-in could not tell them apart. They now match <version>, <product>, and <product>/<version>. Decisions and rejected alternatives: docs/adr/0001-0003. Side effects, both intentional: - show-in/hide-in now trim list entries. Five call sites wrote "core, enterprise" with a space and never matched, so powerbi.md rendered "Your with query permissions for the target database" on Enterprise. Those pages now render as written. - Moving text out of front-matter'd pages exposes pre-existing Vale errors, because Vale under-reports on pages that have front matter. Twenty-one mechanical fixes applied (spacing, Latin abbreviations, two duplicated words); "50th percentile" exempted inline as a standard technical term. The remaining 24 pairs need per-hunk editorial judgment and are deferred. A transitional blocking check keeps them from drifting further; it deletes itself when the manifest empties. Verification: Hugo build clean; zero unresolved placeholders across 5,959 pages; baseline-vs-migrated diff shows 60 v1 pages and 2 v3 pages changed as intended and nothing else, after subtracting build nondeterminism proven by a control build of identical code.
Contributor
Vale Style Check Results
Warnings (8)
✅ Check passed |
Contributor
Release version checkNo release-notes pages with a tracked version changed in this PR. 💡 Badge new features with the versionDocumenting a new feature? Add a version badge in the page frontmatter — the
For inline version text, use |
Contributor
🔗 Link Check Results — Link Check Bot✅ All links are valid
|
| Source File | URL | Issue |
|---|---|---|
content/enterprise_influxdb/v1/administration/identify-version/_index.md |
https://reddit.com/r/influxdb | Error (cached) |
content/enterprise_influxdb/v1/administration/identify-version/_index.md |
https://support.influxdata.com/ | Error (cached): Error (cached) |
content/enterprise_influxdb/v1/concepts/crosswalk/_index.md |
https://support.influxdata.com/ | Network error: SSL certificate not trusted. Use --insecure if site is trusted (e… |
content/enterprise_influxdb/v1/concepts/insights_tradeoffs/_index.md |
https://reddit.com/r/influxdb | Error (cached) |
content/enterprise_influxdb/v1/concepts/insights_tradeoffs/_index.md |
https://support.influxdata.com/ | Error (cached): Error (cached) |
content/enterprise_influxdb/v1/concepts/time-series-index/_index.md |
https://reddit.com/r/influxdb | Error (cached) |
content/enterprise_influxdb/v1/concepts/time-series-index/_index.md |
https://support.influxdata.com/ | Error (cached): Error (cached) |
content/enterprise_influxdb/v1/flux/guides/cumulativesum/_index.md |
https://support.influxdata.com/ | Error (cached): Error (cached) |
content/enterprise_influxdb/v1/flux/guides/cumulativesum/_index.md |
https://reddit.com/r/influxdb | Error (cached) |
content/enterprise_influxdb/v1/flux/guides/fill/_index.md |
https://reddit.com/r/influxdb | Error (cached) |
content/enterprise_influxdb/v1/flux/guides/fill/_index.md |
https://support.influxdata.com/ | Error (cached): Error (cached) |
content/enterprise_influxdb/v1/flux/guides/geo/shape-geo-data/_index.md |
https://support.influxdata.com/ | Network error: SSL certificate not trusted. Use --insecure if site is trusted (e… |
content/enterprise_influxdb/v1/flux/guides/group-data/_index.md |
https://reddit.com/r/influxdb | Error (cached) |
content/enterprise_influxdb/v1/flux/guides/group-data/_index.md |
https://support.influxdata.com/ | Error (cached): Error (cached) |
content/enterprise_influxdb/v1/flux/guides/increase/_index.md |
https://support.influxdata.com/ | Error (cached): Error (cached) |
content/enterprise_influxdb/v1/flux/guides/increase/_index.md |
https://reddit.com/r/influxdb | Error (cached) |
content/enterprise_influxdb/v1/flux/guides/_index.md |
https://support.influxdata.com/ | Network error: SSL certificate not trusted. Use --insecure if site is trusted (e… |
content/enterprise_influxdb/v1/flux/guides/median/_index.md |
https://support.influxdata.com/ | Error (cached): Error (cached) |
content/enterprise_influxdb/v1/flux/guides/median/_index.md |
https://reddit.com/r/influxdb | Error (cached) |
content/enterprise_influxdb/v1/flux/guides/moving-average/_index.md |
https://support.influxdata.com/ | Error (cached): Error (cached) |
Showing first 20 of 60 warnings. See the workflow run for full results.
Full details: workflow run summary and artifact. Last updated: 2026-08-06 14:11:01 UTC
Vale 3.17.0 (the version CI pins) flags two errors that the pre-migration pages never surfaced: - The median stubs' description repeated "(50th percentile)" alongside "median". Vale lints short stubs' front matter, unlike the long pages these replaced. Dropped the redundant parenthetical. - group-data.md used spaced en dashes around an appositive. Replaced with an unspaced em dash per Google style. Pre-existing in both editions. Verified with Vale 3.17.0 rather than the locally installed 3.15.1: vale.sh only enforces its VALE_VERSION pin in CI and the Docker fallback, accepting any local major >= 3.
The link checker only inspects changed files, so these pages had not been checked in a long time. All were already broken on master: - median.md anchors used hyphens (#estimate-tdigest) but Hugo keeps the underscores from the headings (#estimate_tdigest). - collectd.md and graphite.md linked #a-note-on-udp-ip-os-buffer-sizes; Hugo drops the slash in 'UDP/IP', producing #a-note-on-udpip-os-buffer-sizes. - math_operators.md pointed at github.com/influxdb/influxdb (wrong org, 404). The influxdata org URL returns 200. The remaining failure, the dead regex-golang.appspot.com tester, needs an editorial choice of replacement and is tracked in #7623 under area:links, which downgrades it to a warning.
Contributor
There was a problem hiding this comment.
🟡 Changes recommended
Empty shared targets, a bypassable ratchet, and data-shape regressions can blank pages or disable automation.
Once you've addressed the issues Copilot identified, you can request another Copilot review.
This review doesn't count toward merge requirements. Sign up for the private preview to control whether Copilot approvals count.
Pull request overview
Centralizes equivalent InfluxDB v1 OSS and Enterprise documentation to prevent future content drift.
Changes:
- Moves 31 page pairs into shared content with thin product stubs.
- Adds product-aware link and visibility resolution.
- Adds ADRs and a CI divergence ratchet for remaining pairs.
File summaries
| File | Description |
|---|---|
PLATFORM_REFERENCE.md |
Regenerates product path reference. |
data/products.yml |
Changes Enterprise v1 path shape. |
layouts/partials/article/content.html |
Resolves shared-content placeholders. |
layouts/partials/product/content-path.html |
Adds product path resolver. |
layouts/shortcodes/show-in.html |
Expands visibility matching. |
layouts/shortcodes/hide-in.html |
Expands visibility matching. |
docs/adr/0001-share-influxdb-v1-prose-content.md |
Records sharing decision. |
docs/adr/0002-keep-v1-url-roots.md |
Records URL-root decision. |
docs/adr/0003-edition-discrimination-in-shared-v1-content.md |
Records edition matching decision. |
.github/workflows/pr-v1-shared-drift.yml |
Adds drift-check workflow. |
.ci/v1-shared-drift-manifest.json |
Lists remaining divergent pairs. |
.ci/scripts/check-v1-shared-drift.js |
Implements divergence ratchet. |
.ci/scripts/check-v1-shared-drift.test.js |
Tests divergence logic. |
content/shared/influxdb-v1/write_protocols/_index.md |
Shares write-protocol overview. |
content/shared/influxdb-v1/administration/identify-version.md |
Adds identify-version target. |
content/shared/influxdb-v1/concepts/crosswalk.md |
Shares crosswalk content. |
content/shared/influxdb-v1/concepts/insights_tradeoffs.md |
Shares design tradeoffs. |
content/shared/influxdb-v1/concepts/time-series-index.md |
Shares TSI overview. |
content/shared/influxdb-v1/query_language/math_operators.md |
Shares math-operator reference. |
content/shared/influxdb-v1/troubleshooting/_index.md |
Shares troubleshooting index. |
content/shared/influxdb-v1/troubleshooting/systemd.md |
Shares systemd guidance. |
content/shared/influxdb-v1/supported_protocols/_index.md |
Shares protocol index. |
content/shared/influxdb-v1/supported_protocols/collectd.md |
Shares collectd guidance. |
content/shared/influxdb-v1/supported_protocols/graphite.md |
Shares Graphite guidance. |
content/shared/influxdb-v1/supported_protocols/opentsdb.md |
Shares OpenTSDB guidance. |
content/shared/influxdb-v1/supported_protocols/udp.md |
Shares UDP guidance. |
content/shared/influxdb-v1/tools/flux-vscode.md |
Shares VS Code guidance. |
content/shared/influxdb-v1/tools/inch.md |
Shares inch guidance. |
content/shared/influxdb-v1/tools/mcp-server.md |
Adds MCP wrapper. |
content/shared/influxdb-v1/tools/influxd/_index.md |
Shares influxd overview. |
content/shared/influxdb-v1/tools/influxd/config.md |
Shares config command. |
content/shared/influxdb-v1/tools/influxd/run.md |
Shares run command. |
content/shared/influxdb-v1/tools/influxd/version.md |
Shares version command. |
content/shared/influxdb-v1/flux/guides/_index.md |
Shares Flux guide index. |
content/shared/influxdb-v1/flux/guides/cumulativesum.md |
Shares cumulative-sum guide. |
content/shared/influxdb-v1/flux/guides/fill.md |
Shares fill guide. |
content/shared/influxdb-v1/flux/guides/geo/shape-geo-data.md |
Shares geo-shaping guide. |
content/shared/influxdb-v1/flux/guides/group-data.md |
Shares grouping guide. |
content/shared/influxdb-v1/flux/guides/increase.md |
Shares increase guide. |
content/shared/influxdb-v1/flux/guides/median.md |
Shares median guide. |
content/shared/influxdb-v1/flux/guides/moving-average.md |
Shares moving-average guide. |
content/shared/influxdb-v1/flux/guides/rate.md |
Shares rate guide. |
content/shared/influxdb-v1/flux/guides/regular-expressions.md |
Shares regex guide. |
content/shared/influxdb-v1/flux/guides/sort-limit.md |
Shares sorting guide. |
content/influxdb/v1/write_protocols/_index.md |
Sources shared content. |
content/influxdb/v1/administration/identify-version.md |
Sources shared content. |
content/influxdb/v1/concepts/crosswalk.md |
Sources shared content. |
content/influxdb/v1/concepts/insights_tradeoffs.md |
Sources shared content. |
content/influxdb/v1/concepts/time-series-index.md |
Sources shared content. |
content/influxdb/v1/query_language/math_operators.md |
Sources shared content. |
content/influxdb/v1/troubleshooting/_index.md |
Sources shared content. |
content/influxdb/v1/troubleshooting/systemd.md |
Sources shared content. |
content/influxdb/v1/supported_protocols/_index.md |
Sources shared content. |
content/influxdb/v1/supported_protocols/collectd.md |
Sources shared content. |
content/influxdb/v1/supported_protocols/graphite.md |
Sources shared content. |
content/influxdb/v1/supported_protocols/opentsdb.md |
Sources shared content. |
content/influxdb/v1/supported_protocols/udp.md |
Sources shared content. |
content/influxdb/v1/tools/flux-vscode.md |
Sources shared content. |
content/influxdb/v1/tools/inch.md |
Sources shared content. |
content/influxdb/v1/tools/mcp-server.md |
Sources shared content. |
content/influxdb/v1/tools/influxd/_index.md |
Sources shared content. |
content/influxdb/v1/tools/influxd/config.md |
Sources shared content. |
content/influxdb/v1/tools/influxd/run.md |
Sources shared content. |
content/influxdb/v1/tools/influxd/version.md |
Sources shared content. |
content/influxdb/v1/flux/guides/_index.md |
Sources shared content. |
content/influxdb/v1/flux/guides/cumulativesum.md |
Sources shared content. |
content/influxdb/v1/flux/guides/fill.md |
Sources shared content. |
content/influxdb/v1/flux/guides/geo/shape-geo-data.md |
Sources shared content. |
content/influxdb/v1/flux/guides/group-data.md |
Sources shared content. |
content/influxdb/v1/flux/guides/increase.md |
Sources shared content. |
content/influxdb/v1/flux/guides/median.md |
Sources shared content. |
content/influxdb/v1/flux/guides/moving-average.md |
Sources shared content. |
content/influxdb/v1/flux/guides/rate.md |
Sources shared content. |
content/influxdb/v1/flux/guides/regular-expressions.md |
Sources shared content. |
content/influxdb/v1/flux/guides/sort-limit.md |
Sources shared content. |
content/enterprise_influxdb/v1/write_protocols/_index.md |
Sources shared content. |
content/enterprise_influxdb/v1/administration/identify-version.md |
Sources shared content. |
content/enterprise_influxdb/v1/concepts/crosswalk.md |
Sources shared content. |
content/enterprise_influxdb/v1/concepts/insights_tradeoffs.md |
Sources shared content. |
content/enterprise_influxdb/v1/concepts/time-series-index.md |
Sources shared content. |
content/enterprise_influxdb/v1/query_language/math_operators.md |
Sources shared content. |
content/enterprise_influxdb/v1/troubleshooting/_index.md |
Sources shared content. |
content/enterprise_influxdb/v1/troubleshooting/systemd.md |
Sources shared content. |
content/enterprise_influxdb/v1/supported_protocols/_index.md |
Sources shared content. |
content/enterprise_influxdb/v1/supported_protocols/collectd.md |
Sources shared content. |
content/enterprise_influxdb/v1/supported_protocols/graphite.md |
Sources shared content. |
content/enterprise_influxdb/v1/supported_protocols/opentsdb.md |
Sources shared content. |
content/enterprise_influxdb/v1/supported_protocols/udp.md |
Sources shared content. |
content/enterprise_influxdb/v1/tools/flux-vscode.md |
Sources shared content. |
content/enterprise_influxdb/v1/tools/inch.md |
Sources shared content. |
content/enterprise_influxdb/v1/tools/mcp-server.md |
Sources shared content. |
content/enterprise_influxdb/v1/tools/influxd/_index.md |
Sources shared content. |
content/enterprise_influxdb/v1/tools/influxd/config.md |
Sources shared content. |
content/enterprise_influxdb/v1/tools/influxd/run.md |
Sources shared content. |
content/enterprise_influxdb/v1/tools/influxd/version.md |
Sources shared content. |
content/enterprise_influxdb/v1/flux/guides/_index.md |
Sources shared content. |
content/enterprise_influxdb/v1/flux/guides/cumulativesum.md |
Sources shared content. |
content/enterprise_influxdb/v1/flux/guides/fill.md |
Sources shared content. |
content/enterprise_influxdb/v1/flux/guides/geo/shape-geo-data.md |
Sources shared content. |
content/enterprise_influxdb/v1/flux/guides/group-data.md |
Sources shared content. |
content/enterprise_influxdb/v1/flux/guides/increase.md |
Sources shared content. |
content/enterprise_influxdb/v1/flux/guides/median.md |
Sources shared content. |
content/enterprise_influxdb/v1/flux/guides/moving-average.md |
Sources shared content. |
content/enterprise_influxdb/v1/flux/guides/rate.md |
Sources shared content. |
content/enterprise_influxdb/v1/flux/guides/regular-expressions.md |
Sources shared content. |
content/enterprise_influxdb/v1/flux/guides/sort-limit.md |
Sources shared content. |
Review details
- Files reviewed: 105/106 changed files
- Comments generated: 10
- Review effort level: Balanced
We're testing this review assessment. Please use 👍 or 👎 to tell us if it's correct.
Comment on lines
+95
to
+97
| const manifest = readManifest(); | ||
| const baseIdx = argv.indexOf('--base'); | ||
| const head = measure(null, manifest); |
Comment on lines
+474
to
+475
| content_path: | ||
| v1: enterprise_influxdb/v1 |
| clustered: /influxdb3/clustered/admin/identify-version/ | ||
| core: /influxdb3/core/admin/identify-version/ | ||
| enterprise: /influxdb3/enterprise/admin/identify-version/ | ||
| source: /shared/influxdb-v1/administration/identify-version.md |
| @@ -0,0 +1,130 @@ | |||
|
|
|||
| # The UDP Input | |||
| core: /influxdb3/core/admin/identify-version/ | ||
| enterprise: /influxdb3/enterprise/admin/identify-version/ | ||
| enterprise_influxdb_v1: /enterprise_influxdb/v1/administration/identify-version/ | ||
| source: /shared/influxdb-v1/administration/identify-version.md |
| @@ -0,0 +1,2 @@ | |||
|
|
|||
| <!-- //SOURCE content/shared/influxdb3-admin/mcp-server-docs-only.md --> | |||
| @@ -0,0 +1,199 @@ | |||
|
|
|||
| # The Graphite Input | |||
Comment on lines
+24
to
+25
| {{- range (split $showInString ",") -}} | ||
| {{- if in $identifiers (trim . " ") -}}{{- $show = true -}}{{- end -}} |
| {{ if .Params.source }} | ||
| {{ $linkRegex := print (replaceRE `[0-9]` "" $product) "(?:[0-9])*" "/version" }} | ||
| {{ readFile .Params.source | replaceRE $linkRegex (print $product "/" $version) | .RenderString | safeHTML }} | ||
| {{ $contentPath := partial "product/content-path.html" . }} |
Comment on lines
+19
to
+20
| {{- range (split $hideInString ",") -}} | ||
| {{- if in $identifiers (trim . " ") -}}{{- $hide = true -}}{{- end -}} |
regex-golang.appspot.com returns 404; the App Engine app is gone. Removing the entry rather than replacing it: Regex101, already listed on the next line, supports the Golang/RE2 flavor, so the 'Go regex testers' section still points readers at a working tool. The identical link in content/shared/influxdb-v2/query-data/flux/regular-expressions.md is untouched here and stays tracked in #7623.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Part of #7620
What changed
Moved the 31 InfluxDB v1 pages whose OSS and Enterprise copies are provably
equivalent into
content/shared/influxdb-v1/, leaving thin front-matter stubs inboth editions. For those pages, duplication is now structurally impossible rather
than discouraged by convention.
Supporting mechanism:
layouts/partials/product/content-path.html(new) resolves a product's URLroot from
data/products.yml, handling both the map and stringcontent_pathshapes.
layouts/partials/article/content.htmlnow resolves a product-neutral/product/version/placeholder using the page'sproduct/versioncascadeinstead of parsing the URL. The existing
<product-root>/versionform stillworks, including the digit-insensitivity that lets
/influxdb/version/resolveon
influxdb3/*pages.show-in/hide-innow match<version>,<product>, and the composite<product>/<version>.data/products.yml--enterprise_influxdb.content_pathis now aversion-keyed map, matching
influxdb..ci/scripts/check-v1-shared-drift.js(+ 11 unittests),
.ci/v1-shared-drift-manifest.json, and.github/workflows/pr-v1-shared-drift.yml.Decisions and rejected alternatives:
docs/adr/0001-0003.Why
The two v1 trees were coupled by convention only. Nothing failed when a fix
landed in one copy and not the other, so they drifted: 74 overlapping pages
differ by 4,881 lines, including edition-independent Flux guides and OSS links
to a
tools/shell/page that no longer exists.v1 is the only shared pair in this repo whose editions do not share a product
root (
/influxdb/v1/vs/enterprise_influxdb/v1/), which is why the existingplaceholder could not serve it -- one literal string cannot resolve to two roots.
Moving Enterprise v1 under the
influxdbroot was considered and deferred: itchanges 186 URLs and ~1,968 link references, and none of that is needed to stop
the drift (
docs/adr/0002).Impact
Two intentional side effects reach beyond v1. Both are called out because the
title does not imply them:
show-in/hide-innow trim list entries. Five call sites wrote"core, enterprise"with a space, and the untrimmed token never matched, sopowerbi.mdrendered "Database token: Your with query permissions for thetarget database" on Enterprise, Clustered, and Cloud Dedicated. Those pages
now render as written. Affects 2 pages.
because Vale under-reports on pages that have front matter (filed as Vale under-reports on pages with front matter, so product pages are linted less strictly than shared content #7617).
21 mechanical fixes applied -- spacing, Latin abbreviations, two duplicated
words.
50th percentileis exempted inline as a standard technical term.The 24 pairs that need per-hunk editorial judgment (1,508 lines) are not in
this PR. They are tracked in #7620 and guarded by the ratchet, which blocks any PR
that increases divergence in a listed pair. The ratchet is transitional and is
deleted when the manifest empties.
Verification
npx hugoexits 0; 5,959 pages./product/version/or<root>/version/placeholderssitewide.
intended, 0 unintended. Asset fingerprints were normalized, and Hugo build
nondeterminism (~26 pages, filed as Hugo output is not reproducible: shortcode placeholder counter and taxonomy title casing vary between identical builds #7619) was proven with a control build of
identical code and subtracted.
restored;
node --test11/11..vale-instructions.ini(0 errors, 31 files). Codeblock lint,
check-source-paths, andcheck-feedback-linkspass. All pre-commit hooks pass.test:shortcode-examples: 5/6. The one failure,Docs home, can search with mispellings, queries Algolia's hosted index, whichreflects production and cannot be affected by this branch.
Checklist
npx hugo --quiet)