Skip to content

Add "Component versions in recent OpenVox releases" reference page#339

Open
miharp wants to merge 1 commit into
OpenVoxProject:masterfrom
miharp:docs/component-versions-333
Open

Add "Component versions in recent OpenVox releases" reference page#339
miharp wants to merge 1 commit into
OpenVoxProject:masterfrom
miharp:docs/component-versions-333

Conversation

@miharp

@miharp miharp commented Jun 15, 2026

Copy link
Copy Markdown
Contributor

What

Adds docs/_openvox_8x/component_versions.md — a "Component versions in recent OpenVox releases" reference page (the OpenVox analog of PE's component_versions_in_recent_pe_releases), so a reader can see which version of each stack component ships in each release in one place.

component_versions_full

Why this is several tables, not one

Unlike Puppet Enterprise, OpenVox has no single bundling versionopenvox-agent, openvox-server, openvoxdb, and openbolt release on independent version lines (e.g. agent 8.28.0, server 8.13.0, openbolt 5.6.0 — unrelated numbers). A unified matrix would need an invented join key, so each component gets its own table keyed by its own release.

What's generated vs hand-maintained

Generated from upstream component pins (never hand-maintained), via new tasks under references:component_versions:

  • Agent/runtime — OpenFact (bundled, links to OpenFact docs), Ruby, OpenSSL, curl.
  • Server — JRuby, resolved through the server's pinned jruby-utilsjruby-deps.
  • OpenVoxDB — release line.
  • OpenBolt — Ruby, OpenSSL, r10k (its own 5.x line).

Hand-maintained with explicit "not bundled" notes (no upstream pin exists): Java (17, 21) and PostgreSQL (11+, 14+ recommended — matching configure_postgres). openvoxdb-termini tracks openvoxdb and is noted rather than tabled.

Fixes a pre-existing r10k bug

The old agent table listed r10k, but r10k is bundled by openbolt-runtime, not the agent runtime (agent-runtime-8.x) — it never shipped in openvox-agent. r10k is dropped from the agent table and surfaced on the OpenBolt table where it's actually bundled. (Verified: r10k is absent from an installed openvox-agent gem list and present in OpenBolt's.)

Multi-version ready

Per-OpenVox-series tables write to _data/<table>/<nav_key>.yml and the page renders its own series via site.data.<table>[page.nav], so a future 9.x collection gets its own data file with no collision. OpenBolt is independent of the OpenVox major and stays shared. Validated with a throwaway 9.x cutover (8.x and 9.x pages rendered their own data), composing with the cutover runbook from #337.

Implementation notes

  • New lib/puppet_references/release_tables.rb: a ReleaseTable base (shared GitHub releases/contents plumbing) + four thin subclasses.
  • The old agent table is moved off about_agent.md (now a pointer) to avoid duplication; nav entry + collection index link added.
  • Generators wired into build.yaml with a committed-data fallback so a transient GitHub API failure never breaks the build.

Validation

  • Every column verified against running 8.x hosts (agent/server/db) and an installed OpenBolt.
  • rake rubocop, markdown-lint, and jekyll build clean; generated data regenerates byte-identical.

Follow-up (not in this PR)

MAINTAINING.md (added in #337) should gain the per-series rake references:*_versions SERIES=9. step so a maintainer doing the 9.x cutover regenerates these data files. Happy to do that as a separate focused PR.

Part of #333

@miharp miharp requested a review from a team as a code owner June 15, 2026 17:28
@miharp miharp marked this pull request as draft June 15, 2026 17:30
@miharp miharp marked this pull request as ready for review June 15, 2026 17:37
@tuxmea

tuxmea commented Jun 15, 2026

Copy link
Copy Markdown
Contributor

Does OpenBolt also have a requirement for OpenVox? (bolt apply)

@miharp

miharp commented Jun 16, 2026

Copy link
Copy Markdown
Contributor Author

Good question — yes, bolt apply relies on OpenVox in two ways:

  • In OpenBolt: it bundles OpenVox to compile the catalog. The gemspec declares openvox ~> 8.0, and the exact version is resolved at build time (e.g. OpenBolt 5.6.0 bundles OpenVox 8.28.0).
  • On targets: apply_prep installs the openvox-agent package on each target (via openvox_bootstrap::install) to apply the catalog there — no server/agent setup required. Documented in Applying manifest blocks.

I could add an OpenVox column to the OpenBolt table, generated per release from openbolt.gemspec:

OpenBolt release OpenVox Ruby OpenSSL r10k
5.6.0 ~> 8.0 3.2.11 3.0.21 5.0.3

One reservation: this column shows a requirement range (~> 8.0), not an exact version like the others, which is a little inconsistent. Options: (a) the range column above, (b) a prose note instead of a column, or (c) an exact bundled version — but that's only readable from the built package (the repo just pins ~> 8.0, no lockfile), so it'd drift from a clean source pin. Preference?

@tuxmea

tuxmea commented Jun 16, 2026

Copy link
Copy Markdown
Contributor

OK from my side to use a version range, as this is the way how OpenBolt deals with this dependency.

OpenVox ships its components on independent version lines (openvox-agent,
openvox-server, openvoxdb, and OpenBolt all release separately with no shared
version), so there is no single bundled version that answers "what's in this
release?". Add a dedicated reference page with one generated table per component,
each keyed by that component's own release.

- New generators (mirroring AgentReleaseTable) resolve bundled versions from
  upstream component pins: ServerReleaseTable (server -> JRuby via the
  jruby-utils/jruby-deps chain), OpenvoxdbReleaseTable (release tags), and
  OpenboltReleaseTable (openbolt -> Ruby/OpenSSL/r10k). Unresolvable older tags
  skip with a warning; an empty resolve refuses to overwrite committed data.
- Rake tasks references:server_versions, references:openvoxdb_versions,
  references:openbolt_versions, plus an umbrella references:component_versions;
  wired into build.yaml with committed-data fallback.
- Multi-series ready: the per-OpenVox-series tables (agent/server/openvoxdb)
  write into _data/<table>/<nav_key>.yml and the page renders its own series via
  site.data.<table>[page.nav], so a future 9.x collection gets its own data file
  with no collision (validated with a throwaway 9.x cutover). OpenBolt is
  independent of the OpenVox major and stays shared in a single data file.
- Fix a pre-existing bug: the agent table listed r10k, but r10k is bundled by
  openbolt-runtime, not the agent runtime (agent-runtime-8.x), so it does not
  ship in openvox-agent. Drop r10k from AgentReleaseTable and the agent table,
  and surface it in the OpenBolt table where it is actually bundled. Java and
  PostgreSQL are supported-version requirements, not pins, so they are shown as
  hand-maintained notes; openvoxdb-termini tracks openvoxdb and is noted, not
  tabled.
- Move the agent release-contents table off about_agent.md (now a pointer) to
  avoid duplication; add nav entry and repoint the collection index link.

Part of OpenVoxProject#333

Signed-off-by: Michael Harp <mike@mikeharp.com>
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@miharp miharp force-pushed the docs/component-versions-333 branch from 100e97c to 7b3cb40 Compare June 16, 2026 14:06
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants