Skip to content

Commit 7b3cb40

Browse files
miharpclaude
miharp
and
claude
committed
Add "Component versions in recent OpenVox releases" reference page
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 #333 Signed-off-by: Michael Harp <mike@mikeharp.com> Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
1 parent aca4a42 commit 7b3cb40

12 files changed

Lines changed: 503 additions & 184 deletions

File tree

‎.github/workflows/build.yaml‎

Lines changed: 6 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -82,9 +82,13 @@ jobs:
8282
# Build each product/version's reference docs from the pin table in
8383
# _data/products.yml into its collection (see `rake references:all`).
8484
bundle exec rake references:all INSTALLPATH=docs
85-
# Refresh the openvox-agent release-contents table from upstream pins.
86-
# Falls back to the committed _data file if the GitHub API is unreachable.
85+
# Refresh the component-version tables (agent, server, openvoxdb) from
86+
# upstream pins. Each falls back to its committed _data file if the
87+
# GitHub API is unreachable, so a transient failure never breaks the build.
8788
bundle exec rake references:agent_versions || echo 'agent_versions refresh failed; using committed _data'
89+
bundle exec rake references:server_versions || echo 'server_versions refresh failed; using committed _data'
90+
bundle exec rake references:openvoxdb_versions || echo 'openvoxdb_versions refresh failed; using committed _data'
91+
bundle exec rake references:openbolt_versions || echo 'openbolt_versions refresh failed; using committed _data'
8892
bundle exec jekyll build
8993
- name: Archive website
9094
run: |

‎Rakefile‎

Lines changed: 49 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -89,16 +89,62 @@ namespace :references do
8989
end
9090
end
9191

92-
desc 'Generate _data/agent_release_contents.yml from upstream component pins'
92+
# The agent/server/openvoxdb tables are per-OpenVox-series: each writes into a
93+
# file named for the collection's nav_key (e.g. openvox_8x), so the component-
94+
# versions page can render its own series via `site.data.<table>[page.nav]` and
95+
# a future 9.x collection gets its own data file without colliding. The nav_key
96+
# is derived from SERIES ("8." -> openvox_8x) and overridable with NAV_KEY.
97+
openvox_nav_key = lambda do
98+
ENV.fetch('NAV_KEY', "openvox_#{ENV.fetch('SERIES', '8.').gsub(/\D/, '')}x")
99+
end
100+
101+
desc 'Generate _data/agent_release_contents/<nav_key>.yml from upstream component pins'
93102
task :agent_versions do
94-
require 'puppet_references/agent_release_table'
103+
require 'puppet_references/release_tables'
95104
series = ENV.fetch('SERIES', '8.')
96105
min_version = ENV.fetch('MIN_RELEASE', '8.25.0')
97-
path = ENV.fetch('AGENT_VERSIONS_DATA', '_data/agent_release_contents.yml')
106+
path = ENV.fetch('AGENT_VERSIONS_DATA', "_data/agent_release_contents/#{openvox_nav_key.call}.yml")
98107
rows = PuppetReferences::AgentReleaseTable.write_data_file(series:, min_version:, path:)
99108
puts "Wrote #{rows.size} releases to #{path}"
100109
end
101110

111+
desc 'Generate _data/server_release_contents/<nav_key>.yml from upstream component pins'
112+
task :server_versions do
113+
require 'puppet_references/release_tables'
114+
series = ENV.fetch('SERIES', '8.')
115+
min_version = ENV.fetch('MIN_RELEASE', '8.12.0')
116+
path = ENV.fetch('SERVER_VERSIONS_DATA', "_data/server_release_contents/#{openvox_nav_key.call}.yml")
117+
rows = PuppetReferences::ServerReleaseTable.write_data_file(series:, min_version:, path:)
118+
puts "Wrote #{rows.size} releases to #{path}"
119+
end
120+
121+
desc 'Generate _data/openvoxdb_release_contents/<nav_key>.yml from upstream releases'
122+
task :openvoxdb_versions do
123+
require 'puppet_references/release_tables'
124+
series = ENV.fetch('SERIES', '8.')
125+
min_version = ENV.fetch('MIN_RELEASE', '8.12.0')
126+
path = ENV.fetch('OPENVOXDB_VERSIONS_DATA', "_data/openvoxdb_release_contents/#{openvox_nav_key.call}.yml")
127+
rows = PuppetReferences::OpenvoxdbReleaseTable.write_data_file(series:, min_version:, path:)
128+
puts "Wrote #{rows.size} releases to #{path}"
129+
end
130+
131+
desc 'Generate _data/openbolt_release_contents.yml from upstream component pins'
132+
task :openbolt_versions do
133+
require 'puppet_references/release_tables'
134+
# OpenBolt is on its own 5.x line, independent of the OpenVox major, so it uses
135+
# its own OPENBOLT_SERIES / OPENBOLT_MIN_RELEASE rather than the generic
136+
# SERIES / MIN_RELEASE. That keeps an OpenVox 9.x regeneration (SERIES=9.) from
137+
# leaking into OpenBolt, where it would resolve no 9.x releases and abort.
138+
series = ENV.fetch('OPENBOLT_SERIES', '5.')
139+
min_version = ENV.fetch('OPENBOLT_MIN_RELEASE', '5.1.0')
140+
path = ENV.fetch('OPENBOLT_VERSIONS_DATA', '_data/openbolt_release_contents.yml')
141+
rows = PuppetReferences::OpenboltReleaseTable.write_data_file(series:, min_version:, path:)
142+
puts "Wrote #{rows.size} releases to #{path}"
143+
end
144+
145+
desc 'Generate all component-version data files (agent, server, openvoxdb, openbolt)'
146+
task component_versions: %i[agent_versions server_versions openvoxdb_versions openbolt_versions]
147+
102148
task :check do
103149
puts 'No VERSION given to build references for - using latest tag' unless ENV['VERSION']
104150
puts "Building into collection #{ENV.fetch('COLLECTION')}" if ENV['COLLECTION']

_data/agent_release_contents.yml renamed to _data/agent_release_contents/openvox_8x.yml

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,31 +1,31 @@
11
---
2+
- release: 8.28.0
3+
openfact: 5.6.1
4+
ruby: 3.2.11
5+
openssl: 3.0.21
6+
curl: 8.20.0
27
- release: 8.27.0
38
openfact: 5.6.1
49
ruby: 3.2.11
510
openssl: 3.0.20
611
curl: 8.20.0
7-
r10k: 5.0.3
812
- release: 8.26.2
913
openfact: 5.6.0
1014
ruby: 3.2.11
1115
openssl: 3.0.20
1216
curl: 8.19.0
13-
r10k: 5.0.3
1417
- release: 8.26.1
1518
openfact: 5.6.0
1619
ruby: 3.2.11
1720
openssl: 3.0.20
1821
curl: 8.19.0
19-
r10k: 5.0.3
2022
- release: 8.26.0
2123
openfact: 5.6.0
2224
ruby: 3.2.11
2325
openssl: 3.0.20
2426
curl: 8.19.0
25-
r10k: 5.0.3
2627
- release: 8.25.0
2728
openfact: 5.4.0
2829
ruby: 3.2.10
2930
openssl: 3.0.19
3031
curl: 8.18.0
31-
r10k: 5.0.2

‎_data/nav/openvox_8x.yml‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,8 @@
99
link: "system_requirements.html"
1010
- text: About openvox-agent
1111
link: "about_agent.html"
12+
- text: Component versions in recent releases
13+
link: "component_versions.html"
1214
- text: Getting started
1315
items:
1416
- text: Getting started with OpenVox

‎_data/openbolt_release_contents.yml‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
---
2+
- release: 5.6.0
3+
openvox: "~> 8.0"
4+
ruby: 3.2.11
5+
openssl: 3.0.21
6+
r10k: 5.0.3
7+
- release: 5.5.0
8+
openvox: "~> 8.0"
9+
ruby: 3.2.11
10+
openssl: 3.0.20
11+
r10k: 5.0.3
12+
- release: 5.4.0
13+
openvox: "~> 8.0"
14+
ruby: 3.2.10
15+
openssl: 3.0.19
16+
r10k: 5.0.2
17+
- release: 5.3.0
18+
openvox: "~> 8.0"
19+
ruby: 3.2.9
20+
openssl: 3.0.18
21+
r10k: 5.0.2

‎_data/openvoxdb_release_contents/openvox_8x.yml‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
---
2+
- release: 8.14.0
3+
- release: 8.13.0
4+
- release: 8.12.1
5+
- release: 8.12.0

‎_data/server_release_contents/openvox_8x.yml‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
---
2+
- release: 8.14.0
3+
jruby: 9.4.12.1
4+
- release: 8.13.0
5+
jruby: 9.4.12.1
6+
- release: 8.12.1
7+
jruby: 9.4.12.1
8+
- release: 8.12.0
9+
jruby: 9.4.12.1

‎docs/_openvox_8x/about_agent.md‎

Lines changed: 5 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,7 @@ title: "About openvox-agent"
77
[services_agent]: ./services_agent_unix.html
88
[services_apply]: ./services_apply.html
99
[openvox_server]: /openvox-server/latest/
10+
[component_versions]: ./component_versions.html
1011

1112
`openvox-agent` is the core OpenVox package for managed nodes and standalone use.
1213
It bundles the OpenVox runtime and the dependencies needed to run it, so it is the
@@ -45,16 +46,7 @@ even if the core OpenVox language and command behavior stay the same.
4546
For package-specific changes, see the [OpenVox release notes][release_notes] and the
4647
latest [OpenVox Server documentation][openvox_server].
4748

48-
## Release contents of `openvox-agent` 8.x
49-
50-
This table is generated from the upstream component pins for each release.
51-
Regenerate it with `bundle exec rake references:agent_versions`.
52-
53-
<!-- markdownlint-disable MD055 MD056 -->
54-
55-
| OpenVox release | OpenFact | Ruby | OpenSSL | curl | r10k |
56-
| --- | --- | --- | --- | --- | --- |
57-
{% for r in site.data.agent_release_contents %}| {{ r.release }} | {{ r.openfact }} | {{ r.ruby }} | {{ r.openssl }} | {{ r.curl }} | {{ r.r10k }} |
58-
{% endfor %}
59-
60-
<!-- markdownlint-enable MD055 MD056 -->
49+
For the bundled versions of OpenFact, Ruby, OpenSSL, and curl in each
50+
`openvox-agent` release, see
51+
[Component versions in recent OpenVox releases][component_versions], which also
52+
covers the server and database components.

‎docs/_openvox_8x/component_versions.md‎

Lines changed: 123 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,123 @@
1+
---
2+
layout: default
3+
title: "Component versions in recent OpenVox releases"
4+
---
5+
6+
[about_agent]: ./about_agent.html
7+
[openfact]: /openfact/latest/
8+
[openbolt]: /openbolt/latest/
9+
[openbolt_apply]: /openbolt/latest/applying_manifest_blocks.html
10+
[server_install_pre]: /openvox-server/latest/install_pre.html
11+
[openvoxdb_postgres]: /openvoxdb/latest/configure_postgres.html
12+
13+
{% assign nav_key = page.nav %}
14+
15+
This page lists the versions of each stack component shipped in recent OpenVox
16+
releases, so you can answer "what's actually in this release?" in one place.
17+
18+
## Why there are several tables
19+
20+
Unlike a single bundled product, OpenVox ships its components on **independent
21+
version lines**. `openvox-agent`, `openvox-server`, `openvoxdb`, and `openbolt` are
22+
released separately and do not share a version number (for example, the newest
23+
agent, server, and database releases all carry different versions, and OpenBolt is
24+
on its own 5.x line). There is no single "OpenVox platform version" that pins all
25+
of them at once, so each component is shown in its own table, keyed by that
26+
component's release.
27+
28+
The bundled-component columns are **generated** from upstream component pins, so
29+
they don't drift. Columns that aren't bundled or pinned anywhere (Java and
30+
PostgreSQL) are supported-version requirements maintained by hand; see the note
31+
under each table.
32+
33+
<!-- markdownlint-disable MD055 MD056 -->
34+
35+
## Agent and runtime components
36+
37+
These ship inside the `openvox-agent` package (see [About openvox-agent][about_agent]).
38+
The OpenFact column is the **bundled** OpenFact version and links to the
39+
[OpenFact documentation][openfact], which is the authoritative source for OpenFact
40+
changes; this page is only a pointer.
41+
42+
| OpenVox release | OpenFact | Ruby | OpenSSL | curl |
43+
| --- | --- | --- | --- | --- |
44+
{% for r in site.data.agent_release_contents[nav_key] %}| {{ r.release }} | [{{ r.openfact }}][openfact] | {{ r.ruby }} | {{ r.openssl }} | {{ r.curl }} |
45+
{% endfor %}
46+
47+
## Server components
48+
49+
These ship with the `openvox-server` package. JRuby is the bundled version,
50+
resolved from the server's pinned `jruby-utils`/`jruby-deps`.
51+
52+
| OpenVox Server release | JRuby | Java |
53+
| --- | --- | --- |
54+
{% for r in site.data.server_release_contents[nav_key] %}| {{ r.release }} | {{ r.jruby }} | 17, 21 |
55+
{% endfor %}
56+
57+
> **Java is not bundled.** OpenVox Server requires a supported JDK to be installed
58+
> separately. The Java column shows the currently supported major versions, not a
59+
> per-release pin; see [Before you install OpenVox Server][server_install_pre].
60+
61+
## Data components
62+
63+
OpenVoxDB ships in the `openvoxdb` package on its own release line. The
64+
`openvoxdb-termini` package (the terminus plugins that let OpenVox Server and
65+
agents talk to OpenVoxDB) is released in lockstep at the **same version** as
66+
`openvoxdb`, so it is not listed separately.
67+
68+
| OpenVoxDB release | PostgreSQL |
69+
| --- | --- |
70+
{% for r in site.data.openvoxdb_release_contents[nav_key] %}| {{ r.release }} | 11+ (14+ recommended) |
71+
{% endfor %}
72+
73+
> **PostgreSQL is not bundled.** OpenVoxDB connects to a PostgreSQL server you
74+
> install separately (the `puppet-openvoxdb` module can install it for you). The
75+
> PostgreSQL column shows the supported minimum (PostgreSQL 11; version 14 or newer
76+
> recommended), not a per-release pin; see [Configuring PostgreSQL][openvoxdb_postgres].
77+
78+
## OpenBolt
79+
80+
[OpenBolt][openbolt] is the orchestration tool. It is not part of the
81+
agent/server/data stack above and ships on its own **5.x** release line, bundling
82+
its own runtime. See the [OpenBolt documentation][openbolt] for OpenBolt's own
83+
release notes.
84+
85+
OpenBolt is the only OpenVox package that **bundles r10k**. Although r10k is
86+
typically run on a server to deploy environments from a control repo, it is not
87+
shipped in `openvox-server` (or `openvox-agent`); on a server you install it
88+
separately, for example with the `puppet/r10k` module or a `gem install`.
89+
90+
| OpenBolt release | OpenVox | Ruby | OpenSSL | r10k |
91+
| --- | --- | --- | --- | --- |
92+
{% for r in site.data.openbolt_release_contents %}| {{ r.release }} | {{ r.openvox }} | {{ r.ruby }} | {{ r.openssl }} | {{ r.r10k }} |
93+
{% endfor %}
94+
95+
> **The OpenVox column is a requirement, not a pinned version.** OpenBolt bundles
96+
> OpenVox for [`bolt apply`][openbolt_apply], declared in its gemspec as a range
97+
> (`~> 8.0`); the exact version is resolved at build time (for example, OpenBolt
98+
> 5.6.0 bundles OpenVox 8.28.0). For `bolt apply`, OpenBolt compiles the catalog
99+
> with this bundled OpenVox and installs the `openvox-agent` package on targets via
100+
> `apply_prep` — so you don't install OpenVox separately to use it.
101+
102+
<!-- markdownlint-enable MD055 MD056 -->
103+
104+
## Regenerating this page
105+
106+
The agent/runtime, server, OpenVoxDB, and OpenBolt columns are generated from
107+
upstream release metadata. Regenerate the data with:
108+
109+
```bash
110+
bundle exec rake references:component_versions
111+
```
112+
113+
The agent, server, and OpenVoxDB tables are per-OpenVox-series: each task writes a
114+
file named for the collection's nav_key, so the page renders its own series via
115+
`site.data.<table>[page.nav]`. With the 8.x defaults this writes
116+
`_data/agent_release_contents/openvox_8x.yml`,
117+
`_data/server_release_contents/openvox_8x.yml`, and
118+
`_data/openvoxdb_release_contents/openvox_8x.yml`. OpenBolt is independent of the
119+
OpenVox major and is shared across series in `_data/openbolt_release_contents.yml`.
120+
121+
When a 9.x collection is added, run the per-series tasks again with `SERIES=9.`
122+
(and an appropriate `MIN_RELEASE`); they write `…/openvox_9x.yml` files, and the
123+
copied 9.x page reads them automatically through its own `page.nav`.

‎docs/_openvox_8x/index.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -24,7 +24,7 @@ OpenVox operates in two modes:
2424
| `openvox-agent` | OpenVox, OpenFact, Hiera, bundled Ruby and OpenSSL |
2525
| `openvox-server` | JVM-based catalog server; depends on `openvox-agent` |
2626

27-
See [Component versions in openvox-agent](about_agent.html) for exact version tables.
27+
See [Component versions in recent OpenVox releases](component_versions.html) for exact version tables.
2828

2929
## Getting started
3030

0 commit comments

Comments
 (0)