docs: uf setup resolves companion tool RPM versions independently

[jflowers]

Context

PR unbound-force/unbound-force#461 (fixes #455) changes how uf setup constructs RPM download URLs for companion tools (Gaze, Replicator) on Fedora/RHEL systems.

Previous behavior

uf setup used the uf binary's own build-time version (opts.Version) to construct RPM download URLs for all companion tools. This produced 404 errors when companion tool versions diverged from the uf version.

New behavior

Each companion tool's latest release is resolved independently via gh release view before constructing the RPM URL. The resolved tag is validated (repo format, semver format, length bound) before use.

Documentation impact

Any existing documentation describing uf setup's RPM/dnf installation path should be updated to reflect:

1. Companion tools (Gaze, Replicator) are resolved to their own latest release version, not the uf binary version
2. The gh CLI must be installed (or installable) before Gaze/Replicator on dnf-based systems (step ordering dependency)
3. Validation errors may surface new messages: invalid release tag format, release tag too long, invalid repository format

Related

• fix(setup): resolve companion tool versions independently for RPM URLs unbound-force#461
• bug: uf setup constructs RPM URLs using uf's own version for companion tools — version skew causes 404 unbound-force#455

[jflowers]

Triage Analysis

Verdict: VALID | Category: enhancement | Objectivity: objective

Panel Assessment (5/5 unanimous)

This issue is a constitutionally mandated cross-repo documentation request for PR unbound-force/unbound-force#461, which changes how uf setup resolves companion tool RPM versions on Fedora/RHEL systems.

Key Findings

1. Behavioral change is real and well-documented: The issue clearly contrasts previous behavior (used uf binary's own version for all RPM URLs → 404 errors) with new behavior (independent gh release view per companion tool with tag validation). Upstream test coverage is thorough with dedicated regression tests for #455.

2. Security relevance: The change introduces a trust boundary shift — version resolution now depends on live GitHub API access rather than a compile-time constant. Documentation should frame the validation rules (invalid release tag format, release tag too long, invalid repository format) as security controls, not just error handling.

3. Step ordering dependency: The gh CLI must be installed before Gaze/Replicator on dnf-based systems. This prerequisite chain is not currently reflected in website documentation and is important for operational reliability.

4. Consolidation opportunity: Related issues docs: sync dewey RPM install documentation #186 (Dewey RPM install docs), docs: uf setup dnf fallback and curl installer behavior on Linux #160 (dnf fallback/curl installer), and docs: release process automation, Fedora packaging, and supply chain security #115 (release process/Fedora packaging) all touch the same RPM/dnf documentation surface. Consider coordinating these to avoid multiple passes over the same pages and prevent inconsistent documentation states.

Scope

Well-bounded. Three concrete documentation deliverables from one upstream behavioral change. No split needed.

---

Triaged by The Divisor council (5 agents) via /uf.triage-issue