Skip to content

Commit aca4a42

Browse files
miharpmiharp
authored
Merge pull request #337 from miharp/docs/cutover-runbook
Add maintainer runbook for the major-version cutover
2 parents 4c8842f + f13064d commit aca4a42

1 file changed

Lines changed: 197 additions & 0 deletions

File tree

‎MAINTAINING.md‎

Lines changed: 197 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,197 @@
1+
# Maintaining openvox-docs
2+
3+
Maintainer procedures for this site. For day-to-day content contribution and local
4+
preview, see [CONTRIBUTING.md](CONTRIBUTING.md).
5+
6+
## Adding a new major version (cutover)
7+
8+
The site uses a **copy-on-major-release** model. Each major version of a product
9+
lives in its own collection (e.g. `docs/_openvox_8x/`), and `_<product>_latest` is a
10+
symlink to the current stable one. When a product ships a new major, you copy the
11+
collection, register it, pin its references, and — once the new major is the stable
12+
release — promote it to `latest` and freeze the old one. Products version
13+
independently (OpenVox, OpenFact, and OpenBolt have generated references; OpenVox
14+
Server, OpenVoxDB, Ecosystem, and OpenVox Containers are authored-only).
15+
16+
The example below adds **OpenVox 9** alongside OpenVox 8; substitute product/version
17+
as needed.
18+
19+
### How versions are wired (background)
20+
21+
- **Collections** — `docs/_<product>_<major>/`, declared in `_config.yml` under both
22+
`collections:` (permalink) and `defaults:` (which nav to use). `_<product>_latest`
23+
is a **symlink** to the current stable collection dir, so `/<product>/latest/`
24+
serves the same files as `/<product>/<major>.x/`.
25+
- **`_data/products.yml`** — the version registry. Per product: a `label`, which
26+
version `latest` aliases, and (for products with generated references) the
27+
`references:` rake task. Per version: `id`, `label`, `collection`, `base` URL, and
28+
— for generated products — the exact upstream `ref:` tag to build from.
29+
- **Navigation** — `_data/nav/<key>.yml` (sidebar trees), `_data/nav_map.yml`
30+
(which collections map to a nav key), `_data/navigation.yml` (top product bar).
31+
- **Version selector** — reads `products.yml`; it appears automatically once a
32+
product has 2+ versions (so it stays hidden until the first cutover).
33+
- **Reference docs** — generated (not committed) by `rake references:all` from the
34+
pinned tags. The new version builds from its pin; the old version stays frozen at
35+
its pin.
36+
37+
> `_config.yml` collections can't be generated from `products.yml` (Jekyll reads the
38+
> config before `_data`), so they are hand-maintained — keep the two in sync.
39+
40+
### Phase 1 — stand up the new version (preview)
41+
42+
Do this when the new major has a tag to build against (a prerelease/RC is fine), but
43+
is **not yet** the stable release. `latest` stays on the current major.
44+
45+
1. **Copy the collection and its nav file, and stage them** so the sweep in step 2
46+
sees all the authored content:
47+
48+
```console
49+
cp -r docs/_openvox_8x docs/_openvox_9x
50+
cp _data/nav/openvox_8x.yml _data/nav/openvox_9x.yml
51+
git add docs/_openvox_9x _data/nav/openvox_9x.yml
52+
```
53+
54+
Generated reference pages are gitignored within the collection, so `git add`
55+
stages only the authored content — and `git grep` below then skips the generated
56+
pages automatically (they self-update from the new tag at build time).
57+
58+
2. **Sweep the copied authored content for version-specific strings** and review each
59+
in context (page titles, prose, compatibility notes, "upgrading from N" pages, and
60+
the **nav file's** section headings and link text). Target the **major you're
61+
leaving behind** (here, `8`):
62+
63+
```console
64+
git grep -nE 'OpenVox 8|8\.x' -- docs/_openvox_9x _data/nav/openvox_9x.yml
65+
```
66+
67+
Don't forget the nav file — its headings (e.g. "OpenVox 8 Platform") and link
68+
text ("Upgrading OpenVox 8") are authored strings that won't update on their own.
69+
70+
This is a review, **not** a blind find/replace. The hits fall into two kinds:
71+
straightforward current-version labels (page titles, "OpenVox 8 uses…") that bump
72+
to the new major, and version-*specific* content (e.g. "8.x still supports hiera 4
73+
for backward compat", the release-notes list of 8.x releases, "upgrading from 8"
74+
paths) that needs rewriting or judgment for the new major — not a mechanical bump.
75+
Targeting the specific old major (rather than a generic `[0-9]+\.x`) keeps out
76+
noise like Puppet / hiera / function-API versions in code examples.
77+
78+
3. **Register the collection** in `_config.yml`:
79+
80+
```yaml
81+
# under collections:
82+
openvox_9x:
83+
output: true
84+
permalink: '/openvox/9.x/:path:output_ext'
85+
86+
# under defaults:
87+
- scope:
88+
path: ''
89+
type: openvox_9x
90+
values:
91+
nav: openvox_9x
92+
```
93+
94+
4. **Wire up navigation.** The nav file (`_data/nav/openvox_9x.yml`) was already
95+
copied and swept in steps 1–2; adjust it further as the 9.x structure diverges
96+
(its links are relative, so they resolve under `/openvox/9.x/...` automatically).
97+
Then add a **new** entry to `_data/nav_map.yml` whose `nav_key` matches the `nav:`
98+
default from step 3 (do *not* add the collection to the existing 8.x entry —
99+
`nav: openvox_9x` only resolves against a `nav_key: openvox_9x`):
100+
101+
```yaml
102+
- nav_key: openvox_9x
103+
collections: openvox_9x
104+
base: /openvox/9.x/
105+
```
106+
107+
Finally, add the new collection to OpenVox's entry in `_data/navigation.yml` (the
108+
top product bar) so the "OpenVox" link is marked active on the new version's pages
109+
too:
110+
111+
```yaml
112+
- title: OpenVox
113+
url: /openvox/latest/
114+
collections: [openvox_latest, openvox_9x, openvox_8x] # add openvox_9x
115+
```
116+
117+
5. **Add the version to `_data/products.yml`** (newest first), keeping `latest: 8x`
118+
for now:
119+
120+
```yaml
121+
openvox:
122+
label: OpenVox
123+
latest: 8x
124+
references: references:openvox
125+
versions:
126+
- id: 9x
127+
label: "9.x"
128+
collection: _openvox_9x
129+
base: /openvox/9.x/
130+
ref: "9.0.0-rc1" # the prerelease/RC tag to build from
131+
- id: 8x
132+
label: "8.x"
133+
collection: _openvox_8x
134+
base: /openvox/8.x/
135+
ref: "8.28.0"
136+
```
137+
138+
6. **Generate references and build locally to verify:**
139+
140+
```console
141+
bundle exec rake references:all INSTALLPATH=docs
142+
bundle exec jekyll build
143+
bundle exec rake test:links
144+
```
145+
146+
Confirm `/openvox/8.x/`, `/openvox/9.x/`, and `/openvox/latest/` all render, and
147+
that the version selector now shows both `9.x` and `8.x (latest)`.
148+
149+
Open a PR with these changes. On merge, CI regenerates both versions from their pins
150+
and publishes.
151+
152+
### Phase 2 — promote the new version to `latest` (GA)
153+
154+
Do this when the new major becomes the stable release.
155+
156+
1. **Repoint the `latest` symlink:**
157+
158+
```console
159+
ln -sfn _openvox_9x docs/_openvox_latest
160+
```
161+
162+
2. **Point the `latest` collection's navigation at the new version.** The
163+
`/<product>/latest/` pages belong to the `openvox_latest` collection, so their nav
164+
has to move from 8.x to 9.x:
165+
- In `_config.yml`, change the `openvox_latest` defaults scope from
166+
`nav: openvox_8x` to `nav: openvox_9x`.
167+
- In `_data/nav_map.yml`, move `openvox_latest` into the 9.x entry's `collections`
168+
and update the `base:` fields so the frozen 8.x entry points at its own URL and
169+
the 9.x entry owns `/latest/`:
170+
171+
```yaml
172+
- nav_key: openvox_8x
173+
collections: openvox_8x
174+
base: /openvox/8.x/
175+
- nav_key: openvox_9x
176+
collections: openvox_9x|openvox_latest
177+
base: /openvox/latest/
178+
```
179+
180+
3. **In `_data/products.yml`:** set the OpenVox `latest:` to `9x` (a targeted
181+
per-product edit — don't sweep every product's `latest:`), and **freeze 8.x** by
182+
pinning its `ref:` to its final 8.x tag (so the frozen collection stays
183+
reproducible).
184+
185+
4. **No-redirect check:** the site has no redirect mechanism. Once `latest` points at
186+
9.x, any page **removed or renamed** in 9.x will 404 at `/openvox/latest/<page>`
187+
for `latest` bookmarks (the content still lives at `/openvox/8.x/<page>`). Diff the
188+
8.x vs 9.x page sets and decide how to handle removed pages before promoting.
189+
190+
5. Rebuild and verify: `/openvox/latest/` now serves the 9.x content, `/openvox/8.x/`
191+
stays frozen, and the version selector marks 9.x as `latest`.
192+
193+
### Rollback
194+
195+
To back out a cutover: repoint the `_<product>_latest` symlink to the previous
196+
collection, revert the `_config.yml` / `nav_map.yml` / `products.yml` / `_data/nav`
197+
changes, and remove the new `docs/_<product>_<major>/` directory.

0 commit comments

Comments
 (0)