You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
There is no way to tell, from the docs, which OpenVox version introduced a given
feature or config option. The copy-on-major-release model in MAINTAINING.md
freezes each major's collection, but says nothing about tracking when something
changed within a collection's lifetime (e.g. across 8.1 → 8.28). To find the minimum
version needed for a feature, a reader currently has to dig through release notes or
diff old doc snapshots.
Background
Raised in Slack (2026-07-31):
David Sowder (UTA): wants version differences documented in a "living document" as
much as practical, so someone reading the latest docs can see that feature X /
config Y wasn't introduced until version Z, rather than having to go digging
through various doc versions. Compared favorably to Python's docs; Puppet's docs
historically only carried this in release notes, and finding old Puppetlabs doc
versions is difficult.
Yury Bushmelev: would be fine living with a single collection instead of full
copy-per-major, as long as new changes are marked with the version they were
introduced in. Notes the tradeoff: copying a whole collection per major is
operationally easier, but if a feature is backported, docs then need updating in
two places instead of one.
binford2k: suggested a callout/admonition style to highlight version differences
inline on a page.
Proposed options (not mutually exclusive)
1. Inline version-note callouts (binford2k). Add a small shortcode/include,
similar to Python's versionadded::/versionchanged:: directives, e.g. {% version_note "Available since OpenVox 8.3" %}, usable in any collection. Lowest
lift: layers onto the existing copy-on-major model with no architecture change,
authors opt in per page as they touch it.
Doesn't remove the double-maintenance cost the copy-on-major model already has,
just inherits it at a smaller scale. A callout added before a cutover fork
propagates for free (the whole page gets copied); one added after the fork only
lands in the collection it was edited in, so a note describing something true of
both 8.x and 9.x (e.g. a backported feature) has to be added by hand to each.
There's also no mechanism tying a callout to "is this still accurate now that this
page lives in a new major" — MAINTAINING.md's cutover sweep checks for stale
version-name strings ("OpenVox 8", "8.x"), not stale version-note callouts, so
that sweep step would need to account for them too.
2. Single rolling collection instead of copy-per-major (Yury). Replace (or
supplement) the frozen per-major collections with one continuously-updated
collection where changes are annotated with their introduction version, rather than
duplicating the whole tree at every cutover. Bigger lift: would mean rethinking the
cutover model documented in MAINTAINING.md#adding-a-new-major-version-cutover,
and shifts maintenance cost from "copy once per major" to "annotate every change,
including backports, in place."
3. Do nothing beyond release notes. Keep the status quo and rely on release_notes.markdown per collection. Cheapest, but doesn't address the
underlying complaint — release notes require cross-referencing multiple doc
versions to answer "what's the minimum version for X."
Notes
Doesn't need to block the in-progress OpenVox 9 cutover (Add OpenVox 9.x docs collection as a preview (latest stays on 8.x) #430 and follow-ups) —
no reason to pause that work waiting on this decision. But it isn't insulated
from the outcome either: if option 2 is adopted, the frozen per-major
collections it produces (_openvox_8x, _openvox_9x, ...) would likely need to
be migrated into whatever single-collection scheme replaces them.
Option 1 could ship independently and cheaply, and isn't undone by option 2 if
that's adopted later. Option 2 is a larger discussion about the documentation
architecture, has migration cost for collections already cut over, and probably
needs more input before committing to it.
Summary
There is no way to tell, from the docs, which OpenVox version introduced a given
feature or config option. The copy-on-major-release model in
MAINTAINING.mdfreezes each major's collection, but says nothing about tracking when something
changed within a collection's lifetime (e.g. across 8.1 → 8.28). To find the minimum
version needed for a feature, a reader currently has to dig through release notes or
diff old doc snapshots.
Background
Raised in Slack (2026-07-31):
much as practical, so someone reading the latest docs can see that feature X /
config Y wasn't introduced until version Z, rather than having to go digging
through various doc versions. Compared favorably to Python's docs; Puppet's docs
historically only carried this in release notes, and finding old Puppetlabs doc
versions is difficult.
copy-per-major, as long as new changes are marked with the version they were
introduced in. Notes the tradeoff: copying a whole collection per major is
operationally easier, but if a feature is backported, docs then need updating in
two places instead of one.
inline on a page.
Proposed options (not mutually exclusive)
1. Inline version-note callouts (binford2k). Add a small shortcode/include,
similar to Python's
versionadded::/versionchanged::directives, e.g.{% version_note "Available since OpenVox 8.3" %}, usable in any collection. Lowestlift: layers onto the existing copy-on-major model with no architecture change,
authors opt in per page as they touch it.
Doesn't remove the double-maintenance cost the copy-on-major model already has,
just inherits it at a smaller scale. A callout added before a cutover fork
propagates for free (the whole page gets copied); one added after the fork only
lands in the collection it was edited in, so a note describing something true of
both
8.xand9.x(e.g. a backported feature) has to be added by hand to each.There's also no mechanism tying a callout to "is this still accurate now that this
page lives in a new major" —
MAINTAINING.md's cutover sweep checks for staleversion-name strings ("OpenVox 8", "8.x"), not stale version-note callouts, so
that sweep step would need to account for them too.
2. Single rolling collection instead of copy-per-major (Yury). Replace (or
supplement) the frozen per-major collections with one continuously-updated
collection where changes are annotated with their introduction version, rather than
duplicating the whole tree at every cutover. Bigger lift: would mean rethinking the
cutover model documented in
MAINTAINING.md#adding-a-new-major-version-cutover,and shifts maintenance cost from "copy once per major" to "annotate every change,
including backports, in place."
3. Do nothing beyond release notes. Keep the status quo and rely on
release_notes.markdownper collection. Cheapest, but doesn't address theunderlying complaint — release notes require cross-referencing multiple doc
versions to answer "what's the minimum version for X."
Notes
no reason to pause that work waiting on this decision. But it isn't insulated
from the outcome either: if option 2 is adopted, the frozen per-major
collections it produces (
_openvox_8x,_openvox_9x, ...) would likely need tobe migrated into whatever single-collection scheme replaces them.
that's adopted later. Option 2 is a larger discussion about the documentation
architecture, has migration cost for collections already cut over, and probably
needs more input before committing to it.