Skip to content

MAINTAINING.md

Latest commit

 

History

History
295 lines (235 loc) · 12.8 KB

MAINTAINING.md

File metadata and controls

295 lines (235 loc) · 12.8 KB
Raw

Maintaining openvox-docs

Maintainer procedures for this site. For day-to-day content contribution and local preview, see CONTRIBUTING.md.

Adding a new major version (cutover)

The site uses a copy-on-major-release model. Each major version of a product lives in its own collection (e.g. docs/_openvox_8x/), and _<product>_latest is a symlink to the current stable one. When a product ships a new major, you copy the collection, register it, pin its references, and — once the new major is the stable release — promote it to latest and freeze the old one. Products version independently (OpenVox, OpenFact, and OpenBolt have generated references; OpenVox Server, OpenVoxDB, Ecosystem, and OpenVox Containers are authored-only).

The example below adds OpenVox 9 alongside OpenVox 8; substitute product/version as needed.

How versions are wired (background)

  • Collections — docs/_<product>_<major>/, declared in _config.yml under both collections: (permalink) and defaults: (which nav to use). _<product>_latest is a symlink to the current stable collection dir, so /<product>/latest/ serves the same files as /<product>/<major>.x/.
  • _data/products.yml — the version registry. Per product: a label, which version latest aliases, and (for products with generated references) the references: rake task. Per version: id, label, collection, base URL, and — for generated products — the upstream ref: to build from: a series ("8.x", resolved at build time to the newest stable tag in that series) for the current stable version, or an exact tag for a prerelease or a frozen older major.
  • Navigation — _data/nav/<key>.yml (sidebar trees), _data/nav_map.yml (which collections map to a nav key), _data/navigation.yml (top product bar).
  • Version selector — reads products.yml; it appears automatically once a product has 2+ versions (so it stays hidden until the first cutover).
  • Reference docs — generated (not committed) by rake references:all from each version's ref:. The new version builds from its prerelease pin; the old version keeps tracking its series until it is frozen at GA.

_config.yml collections can't be generated from products.yml (Jekyll reads the config before _data), so they are hand-maintained — keep the two in sync.

Phase 1 — stand up the new version (preview)

Do this when the new major has a tag to build against (a prerelease/RC is fine), but is not yet the stable release. latest stays on the current major.

  1. Copy the collection and its nav file, and stage them so the sweep in step 2 sees all the authored content:

    cp -r docs/_openvox_8x docs/_openvox_9x
cp _data/nav/openvox_8x.yml _data/nav/openvox_9x.yml
git add docs/_openvox_9x _data/nav/openvox_9x.yml

    Generated reference pages are gitignored within the collection, so git add stages only the authored content — and git grep below then skips the generated pages automatically (they self-update from the new tag at build time).

  2. Sweep the copied authored content for version-specific strings and review each in context (page titles, prose, compatibility notes, "upgrading from N" pages, and the nav file's section headings and link text). Target the major you're leaving behind (here, 8):

    git grep -nE 'OpenVox 8|8\.x' -- docs/_openvox_9x _data/nav/openvox_9x.yml

    Don't forget the nav file — its headings (e.g. "OpenVox 8 Platform") and link text ("Upgrading OpenVox 8") are authored strings that won't update on their own.

    This is a review, not a blind find/replace. The hits fall into two kinds: straightforward current-version labels (page titles, "OpenVox 8 uses…") that bump to the new major, and version-specific content (e.g. "8.x still supports hiera 4 for backward compat", the release-notes list of 8.x releases, "upgrading from 8" paths) that needs rewriting or judgment for the new major — not a mechanical bump. Targeting the specific old major (rather than a generic [0-9]+\.x) keeps out noise like Puppet / hiera / function-API versions in code examples.

  3. Register the collection in _config.yml:

    # under collections:
openvox_9x:
  output: true
  permalink: '/openvox/9.x/:path:output_ext'

# under defaults:
- scope:
    path: ''
    type: openvox_9x
  values:
    nav: openvox_9x

  4. Wire up navigation. The nav file (_data/nav/openvox_9x.yml) was already copied and swept in steps 1–2; adjust it further as the 9.x structure diverges (its links are relative, so they resolve under /openvox/9.x/... automatically). Then add a new entry to _data/nav_map.yml whose nav_key matches the nav: default from step 3 (do not add the collection to the existing 8.x entry — nav: openvox_9x only resolves against a nav_key: openvox_9x):

    - nav_key: openvox_9x
  collections: openvox_9x
  base: /openvox/9.x/

    Finally, add the new collection to OpenVox's entry in _data/navigation.yml (the top product bar) so the "OpenVox" link is marked active on the new version's pages too:

    - title: OpenVox
  url: /openvox/latest/
  collections: [openvox_latest, openvox_9x, openvox_8x]   # add openvox_9x

  5. Add the version to _data/products.yml (newest first), keeping latest: 8x for now. The new version pins an exact prerelease tag (a series never resolves to a prerelease); the old version keeps its "8.x" series ref so it still picks up 8.x point releases:

    openvox:
  label: OpenVox
  latest: 8x
  references: references:openvox
  versions:
    - id: 9x
      label: "9.x"
      collection: _openvox_9x
      base: /openvox/9.x/
      ref: "9.0.0-rc1"   # the prerelease/RC tag to build from
    - id: 8x
      label: "8.x"
      collection: _openvox_8x
      base: /openvox/8.x/
      ref: "8.x"

  6. Generate references and build locally to verify:

    bundle exec rake references:all INSTALLPATH=docs
bundle exec jekyll build
bundle exec rake test:links

    Confirm /openvox/8.x/, /openvox/9.x/, and /openvox/latest/ all render, and that the version selector now shows both 9.x and 8.x (latest).

Open a PR with these changes. On merge, CI regenerates both versions from their ref:s and publishes.

Phase 2 — promote the new version to latest (GA)

Do this when the new major becomes the stable release.

  1. Port content drift from the old version. The Phase 1 copy is frozen at the moment it was made: edits merged to the old collection afterward are absent from the new one, and nothing surfaces them — they merge without conflict and the new collection's pages are simply older. Find the copy point (the commit that added the new collection) and list every old-collection change since:

    git log $(git log --diff-filter=A --format=%H -1 -- docs/_openvox_9x/index.md)..master \
  -- docs/_openvox_8x _data/nav/openvox_8x.yml

    Port each relevant change onto the new collection — a path-rewritten apply usually works as-is:

    git show <commit> -- docs/_openvox_8x | sed 's|_openvox_8x|_openvox_9x|g' | git apply

    Review ported content for version-specific prose, same as the Phase 1 sweep. Re-run this check immediately before merging the promotion PR; if a docs freeze is ever warranted, it only needs to cover the window between that final check and the merge.

  2. Repoint the latest symlink:

    ln -sfn _openvox_9x docs/_openvox_latest

  3. Point the latest collection's navigation at the new version. The /<product>/latest/ pages belong to the openvox_latest collection, so their nav has to move from 8.x to 9.x:

    • In _config.yml, change the openvox_latest defaults scope from nav: openvox_8x to nav: openvox_9x.

    • In _data/nav_map.yml, move openvox_latest into the 9.x entry's collections and update the base: fields so the frozen 8.x entry points at its own URL and the 9.x entry owns /latest/:

      - nav_key: openvox_8x
  collections: openvox_8x
  base: /openvox/8.x/
- nav_key: openvox_9x
  collections: openvox_9x|openvox_latest
  base: /openvox/latest/

  4. In _data/products.yml: set the OpenVox latest: to 9x (a targeted per-product edit — don't sweep every product's latest:) and switch 9.x from its prerelease pin to the "9.x" series ref so it tracks 9.x point releases. Leave the 8.x "8.x" series ref in place while 8.x still receives maintenance releases, so its generated reference pages keep tracking them. Freeze 8.x by replacing the series ref with its final 8.x tag once the last 8.x release has shipped (so the frozen collection stays reproducible).

  5. No-redirect check: the site has no redirect mechanism. Once latest points at 9.x, any page removed or renamed in 9.x will 404 at /openvox/latest/<page> for latest bookmarks (the content still lives at /openvox/8.x/<page>). Diff the 8.x vs 9.x page sets and decide how to handle removed pages before promoting.

  6. Rebuild and verify: /openvox/latest/ now serves the 9.x content, /openvox/8.x/ stays frozen, and the version selector marks 9.x as latest.

Rollback

To back out a cutover: repoint the _<product>_latest symlink to the previous collection, revert the _config.yml / nav_map.yml / products.yml / _data/nav changes, and remove the new docs/_<product>_<major>/ directory.

Release notes

The newest entries on the release-notes pages for OpenVox (the agent), OpenBolt, OpenVox Server, and OpenVoxDB are generated from the GitHub releases. Older entries are hand-written Markdown on the page itself.

What is generated

rake references:release_notes writes _data/release_notes/<nav>.yml (for example openvox-server_9x.yml) with one record for each stable release in the page's series that is newer than its release_notes_after version in _data/products.yml. _includes/release_notes.html renders the records, newest first, where the page includes it. Each entry has:

  • the heading, such as ## OpenVox Server 9.1.2
  • the release date, which is the GitHub release's publication date in UTC
  • the release type: feature for an x.y.0 release, otherwise bug-fix
  • the link to the GitHub release
  • a collapsed table of the bundled components that changed since the previous release, from the openvox-sbom-tools SBOMs. The table appears once the SBOMs for both releases are merged there.

CI runs the task on every build, and falls back to the committed data files if the GitHub API is unreachable, so a new release needs no docs PR. It appears with the next production build. If nothing else is merging, start one from the "Automatically publish new content" workflow's Run workflow button. To preview locally, run bundle exec rake references:release_notes before jekyll build. The generator and the highlights plugin have unit tests in spec/; run bundle exec rake spec after changing them.

CVE tables are not generated yet. Until they are, add a hand-written ### Security Issues Resolved in <version> table to the release's highlights file.

Adding highlights

Put anything a release needs beyond the generated text in _release_highlights/<nav>/<version>.md, for example _release_highlights/openvox-server_9x/9.1.2.md. The file is rendered after the GitHub link, as part of that release's entry:

---
type: security
---

Notable changes in this release:

- The `openvox-server` package now requires `openvox-agent` 9.2.2 or later.
  • The front matter is optional. type replaces the generated release type.
  • Start with a paragraph or a list, not a heading. Use ### headings for sections inside the entry, as the hand-written entries do.
  • Keep to what readers need to act on or won't find on the GitHub release: package requirement changes, upgrade steps, links to related releases of other components.
  • The build warns about a highlights file whose version has no generated entry, for example because of a typo in the file name.

Switching a page to generated entries

  1. In _data/products.yml, give the product a release_notes block with its GitHub repo and sbom package name, and set release_notes_after on the version to the newest release that has a hand-written entry.
  2. Add {% include release_notes.html product="<name>" %} to the page above the first hand-written entry, where <name> is the product name used in the entry headings.
  3. Run bundle exec rake references:release_notes and commit the new data file.