v0.2 scope — roadmap refactor and rtb-vcs split¶

Status: IMPLEMENTED — § 16 of the framework spec has been updated with the diff in § 2, the four per-crate specs are APPROVED, and this document records the decision trail. Target document: docs/development/specs/rust-tool-base.md § 16 Roadmap. Rationale driver: GTB-parity on release-source support at the moment rtb-update ships.

1. Motivation¶

The current framework spec § 16 targets rtb-vcs at v0.5 and notes that rtb-update (v0.2) will "start with a hard-coded GitHub path via self_update and migrate to ReleaseProvider when this crate ships". That commitment was made before we audited go-tool-base's release package.

GTB actually ships six release backends on day one:

Shipping rtb-update without this parity would mean RTB-built tools have materially fewer distribution options than GTB-built tools. That's the user-observable product difference the companion framework is meant to erase, not introduce.

The cheapest way to close the gap is to pull the release-provider slice of rtb-vcs forward to v0.2 and leave the broader git-operations slice (the Repo type, gix/git2 integration, commit/diff/blame) at v0.5 as originally planned. GTB itself has a clean seam between pkg/vcs/release/ and pkg/vcs/repo/ — RTB can mirror that split as two milestones on the same crate.

2. Proposed roadmap changes¶

Replace the Pending section of § 16 with:

 ### Pending

-- **0.2** — `rtb-update` (self-update with signature verification),
-  `rtb-docs` (TUI + markdown), `rtb-redact` helper for telemetry
-  attrs, `rtb-config::subscribe()` + hot-reload, OTLP sink in
-  `rtb-telemetry`, HTTP JSON sink in `rtb-telemetry`.
+- **0.2** — `rtb-redact` (first, unblocks telemetry redaction),
+  `rtb-vcs` v0.1 (release-provider slice only: `ReleaseProvider`
+  trait + GitHub / GitLab / Bitbucket / Gitea / Codeberg / Direct
+  backends), `rtb-update` (self-update with signature verification,
+  consumes `rtb-vcs`), `rtb-docs` (TUI + markdown),
+  `rtb-config::subscribe()` + hot-reload, OTLP sink in
+  `rtb-telemetry`, HTTP JSON sink in `rtb-telemetry`.
   Remove the `update`/`docs`/`mcp` stubs from `rtb-cli`'s built-ins
   as each real crate registers its own command.
 - **0.3** — `rtb-ai` (genai + Anthropic-direct for caching/agents),
   `rtb-mcp` (`rmcp` SDK). Structured output via `schemars` +
   `jsonschema`.
 - **0.4** — `rtb-tui` (Wizard, tables, spinners), `rtb-cli`
   `credentials`/`telemetry`/`config-set` subcommands.
-- **0.5** — `rtb-vcs` (octocrab + gitlab + gix). Release providers
-  behind the `ReleaseProvider` trait. `rtb-update` switches to it.
+- **0.5** — `rtb-vcs` v0.2 (git-operations slice: the `Repo` type,
+  `gix`/`git2` adapters, commit/diff/blame/clone). Extends the
+  crate that shipped its release slice at v0.2.
 - **0.6** — `rtb-cli-bin` scaffolder with `rtb new`, `rtb generate`,
   `rtb regenerate`.
 - **1.0** — API freeze, semver commitment, full docs site.

3. Implications¶

3.1 rtb-app::metadata::ReleaseSource expands¶

The current enum (rtb-app/src/metadata.rs) only has Github and Gitlab. v0.2 adds Bitbucket, Gitea, Codeberg, Direct.

#[derive(Debug, Clone, PartialEq, Eq, serde::Deserialize, serde::Serialize)]
#[serde(tag = "kind", rename_all = "lowercase")]
#[non_exhaustive]
pub enum ReleaseSource {
    Github { host: String, owner: String, repo: String },
    Gitlab { host: String, owner: String, repo: String },
    // new in v0.2:
    Bitbucket { host: String, workspace: String, repo_slug: String },
    Gitea { host: String, owner: String, repo: String },
    Codeberg { owner: String, repo: String },  // host hard-coded to codeberg.org
    Direct { version_url: String, asset_url_template: String },
}

• #[non_exhaustive] is already in place, so adding variants is a minor-version change under Rust semver. Downstream tools that matched exhaustively were already warned not to.
• The Codeberg variant deliberately omits host because Codeberg is the single hosted Gitea instance at codeberg.org and hiding that as a fixed constant gives users clearer intent at the config layer. A tool that wants to point at a different Gitea instance uses Gitea directly.

3.2 Version bump¶

The ReleaseSource expansion plus new crates means this lands as 0.2.0, not a further 0.1.x. That aligns with the "pre-1.0 minor bumps may break" policy recorded in CHANGELOG.md.

3.3 rtb-vcs Cargo manifest¶

The crate already exists as a stub with version = "0.1.1" (workspace inherit) and empty src/lib.rs. v0.2 replaces the stub with the release-provider implementation; the stub-header doc comment is rewritten to reflect "Status: shipped v0.1 (release slice); git-operations slice targeted for v0.5 as rtb-vcs v0.2." No Cargo.toml-level changes are needed for the milestone split — cargo versions track the rtb-vcs crate itself, independently of the roadmap milestones.

3.4 Documentation cascade¶

After this addendum is approved:

• docs/components/index.md — move rtb-vcs from the v0.5 table to the v0.2 table, annotate "(release slice)".
• docs/development/specs/rust-tool-base.md § 16 — apply the diff in §2.
• Per-crate v0.1 specs for rtb-redact, rtb-vcs, rtb-update, rtb-docs are drafted alongside this addendum (same PR, all status DRAFT).

4. Non-goals for v0.2¶

• Writeable release operations — creating releases, uploading assets, editing tags. ReleaseProvider is read-only at v0.2. GTB's Provider interface matches (GetLatest, GetByTag, List, DownloadAsset — no write methods).
• Webhook or poll-based release discovery. rtb-update polls on demand; continuous discovery is a future tool-author concern.
• Non-Ed25519 signature schemes. v0.2 is Ed25519 + SHA-256 only, same as GTB's goreleaser default. A pluggable verifier trait can be added later without breaking the 0.2 surface.
• Binary-diff / delta updates. Full-binary self-replace only; delta updates are a v0.3+ concern if a real need materialises.

5. Open questions¶

• O1 — Codeberg as distinct variant vs alias. Above I kept Codeberg as a first-class variant for clarity. An alternative is Gitea { host: "codeberg.org", ... } with a Codeberg convenience constructor. Tiny difference; flag for discussion before impl.
• O2 — ReleaseSource::Direct schema. version_url returns a plain-text or JSON version indicator; asset_url_template uses {version} / {target} placeholders. Needs a documented template grammar before rtb-update can consume it.
• O3 — Auth token scoping. Each provider consumes a SecretString supplied by rtb-credentials. The naming convention for the credential reference — release.github.token vs update.token vs per-source buckets — affects how tool authors document required credentials. Proposed resolution: per-source, mirroring GTB (release.{type}.token).
• O4 — GitHub App auth. GTB supports GitHub Enterprise with both PAT and GitHub App JWT auth. v0.2 RTB could ship PAT only and add App auth in 0.2.x, or do both at launch. PAT is the 80% case. Leaning: PAT at v0.2, App auth slated for 0.2.x.

6. Approval gate¶

This addendum is implemented when (a) § 16 of the framework spec is updated with the diff in § 2, (b) the four per-crate DRAFT specs land with status: APPROVED, and © a commit bumps this document's own status to IMPLEMENTED.