Skip to content

Commit 100e97c

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 100e97c

12 files changed

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