influxdata / influxdata/docs-v2
Phase A: reconcile the 24 remaining InfluxDB v1 OSS/Enterprise page pairs into shared content
- Dominant language
- JavaScript
- Stars
- 82
- Forks
- 326
- Avg merge
- 1d 1h
- Merged PRs (30d)
- 82
Description
## Goal
Finish the InfluxDB v1 shared-content migration by reconciling the 24 page pairs
that still exist as two copies, moving each into `content/shared/influxdb-v1/`.
When the list is empty, delete the transitional guard.
Phase C (already merged) moved the 31 pairs whose copies were *provably*
equivalent and built the mechanism: the `/product/version/` path placeholder
resolved from `data/products.yml`, `show-in`/`hide-in` matching on
`/`, and a blocking divergence ratchet over what remains.
Background and rejected alternatives are in `docs/adr/0001`-`0003`.
## Why these are separate from phase C
The 31 already-migrated pairs needed no editorial judgment -- `diff -w` proved
nothing was lost. These 24 differ by **1,508 lines** that require picking a
winner per hunk. There is no rule that decides it:
- Git history could not arbitrate at the time, because the clone was shallow and
grafted at `c32e05175`. That is fixed -- `git fetch --unshallow` restores
10,513 commits, so `git log -L` and `git blame` now work on these files. **Use
them.** Reconciling by taste is how this content drifted in the first place.
- "Enterprise is the newer copy" is **false** for this set. It was measured and
it does not hold: Enterprise's `exists.md` is fuller and correctly links to v1
pages, while OSS's `mathematic-operations.md` has the better REPL link.
## Worklist
Tracked in `.ci/v1-shared-drift-manifest.json`, which CI keeps honest -- remove
an entry when its page moves to `content/shared/influxdb-v1/`. Current state
(`node .ci/scripts/check-v1-shared-drift.js --report`):
| diverging lines | page |
| --- | --- |
| 338 | `flux/flux-vs-influxql.md` |
| 183 | `concepts/glossary.md` |
| 152 | `flux/guides/conditional-logic.md` |
| 94 | `flux/guides/calculate-percentages.md` |
| 88 | `flux/get-started/transform-data.md` |
| 75 | `flux/guides/mathematic-operations.md` |
| 69 | `flux/guides/scalar-values.md` |
| 67 | `flux/guides/join.md` |
| 58 | `flux/get-started/syntax-basics.md` |
| 56 | `flux/guides/monitor-states.md` |
| 51 | `flux/guides/histograms.md` |
| 48 | `flux/guides/exists.md` |
| 33 | `flux/guides/window-aggregate.md` |
| 32 | `flux/guides/flux-in-dashboards.md` |
| 30 | `flux/guides/sql.md` |
| 29 | `flux/guides/geo/filter-by-region.md` |
| 20 | `flux/guides/manipulate-timestamps.md` |
| 17 | `flux/guides/percentile-quantile.md` |
| 16 | `flux/get-started/_index.md` |
| 16 | `flux/guides/geo/group-geo-data.md` |
| 13 | `flux/guides/query-fields.md` |
| 12 | `flux/guides/first-last.md` |
| 8 | `flux/guides/geo/_index.md` |
| 3 | `flux/installation.md` |
All but the glossary are Flux content, which is edition-independent -- divergence
there is accidental by definition, so a correct answer exists for each hunk.
## Known anomalies
- **`concepts/glossary.md`** is additive, not conflicting. Enterprise defines 10
terms OSS does not (`meta node`, `data node`, `meta service`, `data service`,
`grant`, `permission`, `role`, `replication factor (RF)`, `passive node`,
`web console`). Merge with `{{% show-in "enterprise_influxdb/v1" %}}` blocks
per term. Reconcile the near-duplicates: OSS `replication factor` vs
Enterprise `replication factor (RF)`.
- **`flux/guides/geo/_index.md`** links a Flux stdlib path that resolves in
**neither** edition. Enterprise's `built-in/outputs/to` is the pre-0.65 layout;
OSS's `influxdata/influxdb/to` does not resolve either. Fix both, do not pick a
winner.
- **`flux/installation.md`** is genuinely edition-specific IA:
`administration/config.md` (OSS) vs `administration/configure/` (Enterprise).
It needs a conditional or the resolved token, not a single literal.
- **Cross-product links.** These pages carry roughly 200 links per edition into
`/influxdb/v2/`, `/flux/v0/`, and `/influxdb3/`, and the two editions disagree
on some targets. Merging freezes each choice into both products at once, so
verify targets resolve before merging rather than after.
- **Vale.** Moving text out of front-matter'd pages exposes pre-existing style
errors (see #7617), and `pr-vale-check.yml` blocks on errors. Budget for it;
phase C surfaced 22 across 31 files.
## Definition of done
- All 24 pairs listed above are in `content/shared/influxdb-v1/`, with
front-matter stubs in both editions.
The original second item -- delete the drift checker, its test, the manifest, and
`.github/workflows/pr-v1-shared-drift.yml` -- no longer applies. It assumed these
24 pairs were the last duplicated v1 pages. Thirty more exist and were never
listed in the manifest. #7662 tracks them, the manifest now lists them, and the
checker stays in place until that issue is done.
## Out of scope
Pages whose editions genuinely differ (clustering, hardware sizing, upgrade
paths) stay as separate files, per `docs/adr/0001`. Moving Enterprise v1 under
the `influxdb` URL root is deliberately deferred, per `docs/adr/0002`.
## Terminology
- **Edition** -- InfluxDB v1 OSS or v1 Enterprise. Both cascade `version: v1`;
only `product` distinguishes them, which is why `show-in` needed the composite
`/` form.
- **Edition root** -- the URL prefix owned by an edition: `/influxdb/v1/` or
`/enterprise_influxdb/v1/`. The v1 pair is the only shared pair in this repo
whose editions do not share a root.
- **Free file** -- a pair whose two copies are *provably* equivalent, so merging
discards nothing: identical after normalizing the edition root, or differing
only by whitespace (`diff -w` is the proof). Phase C moved exactly these.
- **Edition-neutral** -- content whose correctness does not depend on edition
(Flux syntax, InfluxQL spec, line protocol). Divergence here is accidental by
definition, which is why the remaining Flux pages are worth reconciling.
- **Divergence ratchet** -- the transitional rule that a deferred pair's
divergence may hold or shrink, never grow.
## Baseline measurements (at phase C)
| | count |
| --- | --- |
| OSS v1 pages / Enterprise v1 pages | 127 / 186 |
| Overlapping paths | 95 |
| Fully byte-identical | 1 |
| Body-identical (front matter stripped) | 13 |
| Identical after edition-root normalization | 21 |
| Genuinely divergent | 74 (4,881 lines) |
| Migrated in phase C | 31 |
| Remaining (this issue) | 24 (1,508 lines) |
The gap between 95 overlapping paths and 55 in scope is deliberate: pages whose
editions genuinely differ are out of scope per `docs/adr/0001`.
Contributor guide
No contributing guide indexed for this repository
Research direction
Start with `.ci/v1-shared-drift-manifest.json`, the 24 listed page pairs, and `docs/adr/0001`-`0003`; fetch the full Git history and run `node .ci/scripts/check-v1-shared-drift.js --report`. Reconcile each pair using the documented history and anomalies, verify links and Vale checks, and finish with all 24 pages under `content/shared/influxdb-v1/`, edition stubs, and updated manifest entries.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- git, javascript
- Domain
- documentation, tooling
- Issue type
- Documentation
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Active
- Clarity
- Clearly specified
- Newbie friendliness
- 35/100