govoplan/docs/RELEASE_CONSOLE.md

GovOPlaN Release Console

The release console is a local operator tool for planning and executing GovOPlaN releases. It belongs to the govoplan meta repository because it works across all local checkouts, release scripts, module manifests, migration audits, catalog files, Git state, and signing keys.

The current implementation has a read-only dashboard plus guarded local candidate/publish actions:

• inspect repositories from repositories.json
• show dirty, ahead, behind, missing, no-HEAD, and tag state
• show local package catalog and keyring state
• optionally run release/dev migration audits
• propose next actions without executing them
• compare local catalog/keyring JSON with the published channel and public keyring when online checks are enabled
• configure target versions per release unit in the web UI
• select the repositories that should advance through checkboxes
• generate dry-run selective release plans for independently versioned packages
• generate signed catalog candidates for the selected release units
• preview/apply/push reviewed catalog candidates behind explicit confirmations

Start it from the meta repository:

./.venv/bin/python tools/release/release-console.py

The server binds to 127.0.0.1 by default and prints a URL containing a local API token. Open that URL in a browser on the same machine.

The web UI starts with a repository table. Each repository can be checked independently and assigned its own target version. Repositories without version metadata remain visible so they can be planned as initial releases. Build Plan shows the dry-run commands for the selected rows, and Generate Candidate creates a signed catalog candidate that advances only selected repositories that already have a catalog entry.

The release-control area above the repository table is read-only and is meant to become the central release cockpit. It shows:

• local and published channel health
• catalog/keyring drift
• signature and trusted-key status
• published module versions and refs
• local checkout version drift against the catalog
• catalog-declared interface compatibility

The target-version control can generate the next major, minor, or subversion from the current base version. Manual target input accepts explicit versions such as 0.2.0 or 0.2.0-alpha1, but requires the first three version numbers to move forward.

Plain repository pushes are separate from catalog publication. Preview Push shows the selected repository push commands. Push Selected requires PUSH in the repository push confirmation field.

The catalog workflow panel can also operate on the same selected rows:

• Generate creates a signed candidate below runtime/release-candidates/.
• Preview validates a candidate and shows what would be copied into the website repository.
• Apply + Tag requires APPLY in the confirmation field.
• Push requires PUSH in the confirmation field.

The default signing key is $HOME/.config/govoplan/release-keys/release-key-1.pem when no signing key is entered in the UI.

Generate a selective release plan from the terminal:

./.venv/bin/python tools/release/release-plan.py \
  --repo govoplan-files \
  --target-version 0.1.9 \
  --channel stable \
  --online

--online compares the local catalog/keyring with the published channel and published keyring. Use --remote-tags only when the plan also needs to check Git remotes for tag existence; that can be slower across the full repository set.

Build a signed selective catalog candidate:

KEY_DIR="$HOME/.config/govoplan/release-keys"

./.venv/bin/python tools/release/release-catalog.py selective \
  --repo-version govoplan-files=0.1.9 \
  --channel stable \
  --catalog-signing-key "release-key-1=$KEY_DIR/release-key-1.pem"

This writes candidate catalog/keyring files below runtime/release-candidates/, generates the browsable module directory below modules/, validates the signed candidate with the module installer validator, and reports whether the candidate catalog/keyring match the currently published channel. It does not publish to the website repository.

Regenerate the browsable module directory from an existing catalog/keyring:

./.venv/bin/python tools/release/release-catalog.py module-directory \
  --catalog ../addideas-govoplan-website/public/catalogs/v1/channels/stable.json \
  --keyring ../addideas-govoplan-website/public/catalogs/v1/keyring.json \
  --output-dir runtime/module-directory-preview \
  --channel stable

Preview publication of a reviewed candidate:

./.venv/bin/python tools/release/release-catalog.py publish-candidate \
  --candidate-dir runtime/release-candidates/stable-YYYYMMDD-HHMMSS \
  --channel stable

Apply the reviewed candidate into the website repository without pushing:

./.venv/bin/python tools/release/release-catalog.py publish-candidate \
  --candidate-dir runtime/release-candidates/stable-YYYYMMDD-HHMMSS \
  --channel stable \
  --apply \
  --commit \
  --tag

Push is a separate explicit flag:

./.venv/bin/python tools/release/release-catalog.py publish-candidate \
  --candidate-dir runtime/release-candidates/stable-YYYYMMDD-HHMMSS \
  --channel stable \
  --apply \
  --commit \
  --tag \
  --push

Published channels are expected below the public catalog base URL:

• https://govoplan.add-ideas.de/catalogs/v1/channels/stable.json
• https://govoplan.add-ideas.de/catalogs/v1/keyring.json

The console treats channels as release artifacts. A package can advance without forcing every repository to the same tag, but channel publication must preserve the unchanged package versions, validate interface compatibility, sign the updated catalog, and keep the published keyring healthy.

Published Module Directory

The target release repository is an online, browsable module directory. The catalog remains the machine-readable channel entry point, but the published space should also expose a tree that operators and installations can inspect:

• /catalogs/v1/channels/<channel>.json describes the active channel state.
• /catalogs/v1/keyring.json publishes trusted release signing keys.
• /catalogs/v1/modules/<module>/<version>/manifest.json describes one published module version, including repository refs, package refs, contracts, compatibility windows, signatures, and available artifacts.
• /catalogs/v1/modules/<module>/index.json lists available versions for one module.
• /catalogs/v1/modules/index.json lists all published modules.

Gitea tags/releases remain the source release anchors. The public GovOPlaN catalog directory becomes the installation-facing release repository that points to those anchors and carries structured compatibility information.

Selective catalog candidates now include this directory tree. Publishing a candidate copies the channel catalog, keyring, and modules/ tree into the website repository together.

Current limitation: selective catalog generation updates existing catalog entries. Initial catalog entry synthesis for brand-new modules is still a separate backend slice.

Direction

The console should grow in slices:

1. Read-only dashboard and next-action suggestions.
2. Release plan builder that writes explicit JSON plans.
3. Dry-run executor that shows exact commands and expected file changes.
4. Apply executor for commit, tag, push, artifact build, signing, and catalog publication.
5. Compatibility planner for manifest contracts and version ranges.
6. Install/test workflow that validates a release from tags or catalog entries.

All mutation must stay explicit: plan first, dry run second, apply only after a clear confirmation.