Skip to content

Track version-introduced info for features/config across doc versions #431

Description

@miharp

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.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.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions