Skip to content

docs/_openvoxdb_8x: Clean up and modernize collection #206

@miharp

Description

@miharp

The `_openvoxdb_8x` collection was ported from PuppetDB docs and needs a systematic
cleanup pass. 95 files, ~1,933 instances of upstream branding to update, plus structural
and content issues found in a thorough audit.

1. Rebrand (highest priority — pervasive) ✅ Done in #207

  • Replace `PuppetDB` / `puppetdb` → `OpenVoxDB` / `openvoxdb` across all 95 files
  • Update GitHub links from `github.com/puppetlabs/puppetdb` → `github.com/OpenVoxProject/openvoxdb`
  • Update Forge module URLs → `https://forge.puppet.com/modules/puppet/openvoxdb\`
  • Audit `Puppet®`, `Puppet Labs` references — removed "generated by Puppet®", "Puppet Labs® issue tracker", "Puppet Labs Status API" framing
  • Update `CONTRIBUTING.md` — Jira tracker link replaced with GitHub issues
  • Replace remaining "PuppetDB" references in `_data/nav/openvoxdb_8x.yml`

Intentionally deferred from rebrand scope:

2. Structural fixes (quick wins) ✅ Done in #234

  • Remove duplicate: `index.md` and `overview.markdown` have identical content — remove one, keep the other
  • Add missing YAML frontmatter to `acceptance_tests.markdown` (currently has none)
  • Add missing YAML frontmatter to `configure_postgres.markdown` (currently has none)
  • Audit ~22 pages not linked from `_data/nav/openvoxdb_8x.yml` — add them, or decide to intentionally omit them (down from ~62; API v4 query endpoints, PQL/AST docs, tutorials, curl tips, and most wire formats were already added to nav):
    • Operational: `logging.html`, `migration_coordination.html`, `testing_storage_changes.html`, `acceptance_tests.html`
    • Older wire format versions (likely intentional): catalog v6–v8, facts v4, reports v5–v7
    • Missing wire formats: `catalog_inputs_format_v1.html`, `configure_expiration_format_v1.html`
    • Missing query endpoints: `api/query/v4/catalog_inputs.html`, `catalog_input_contents.html`

3. Content accuracy ✅ Done in #239 (pending merge)

  • Fix placeholder/corrupted text: `xxxxxz` string in `release_notes_6.markdown`
  • Fix `"Puppet DB"` (with space) → `"OpenVoxDB"` in `release_notes_6.3.markdown`
  • Update PostgreSQL version support table — updated minimum to PG 14+ (OpenVoxDB 8.x requirement); clarified supported versions
  • Remove "Experimental" label on PQL in `api/query/v4/pql.markdown` (PQL is stable)
  • Review deprecated Metrics API docs (`api/metrics/v2/jolokia.markdown`) — reviewed; no evidence of formal deprecation, lint-cleaned and updated
  • Fix outdated external links:
    • PostgreSQL docs URLs updated from versioned `/static/` paths → `/current/`
    • `puppet.com/docs/puppetdb/latest/configure.html#vardir` in `maintain_and_tune.markdown` — already an internal link, no change needed

4. Release notes cleanup ✅ Done in #240 (pending merge)

  • Resolve overlap between `release_notes.markdown` and `release_notes_8.markdown`
  • Consolidate to a single `release_notes.markdown` covering only OpenVoxDB-era releases (8.9.0–8.13.0), matching the style used for OpenVox Server release notes
  • Remove legacy PuppetDB release notes files (`release_notes_5.2`, `release_notes_6`, `release_notes_6.0`, `release_notes_6.3`, `release_notes_7`, `release_notes_8`, `release_notes_older`) — not linked in nav and out of scope for this project
  • Move release notes to the top of the "General information" nav section

Notes

  • Old release notes for PuppetDB 1–7 (`release_notes_older.markdown`, `release_notes_5.2.markdown`, etc.) are intentionally left as historical record — no changes needed there
  • Technical names kept as-is (verified against https://github.com/voxpupuli/puppet-openvoxdb): service name `puppetdb`, system paths `/etc/puppetlabs/puppetdb/`, database name `puppetdb`, `[puppetdb]` INI section, `storeconfigs_backend = puppetdb`, `reports = store,puppetdb`, `puppetdb.conf` filename

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type
    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions