Document Repo management CLI's (pkg6repo and pkg6recv) #9

New issue

Open

opened 2026-02-07 14:12:03 +00:00 by Toasterson · 0 comments

Toasterson commented

2026-02-07 14:12:03 +00:00

(Migrated from codeberg.org)

Maintainer decisions — 2026-09-22

Use an mdBook operator guide PLUS installed CLI man pages. Man pages must follow illumos voice, structure, section conventions and formatting; raw generated clap help is not sufficient without editorial review. Use the local illumos man pages as reference.

Guide minimum: IPS/SMF installation and upgrades/config preservation; direct and reverse-proxy TLS; ACME HTTP-01 and Cloudflare/Gandi DNS-01; single certificate owner; .p5p import handoff, atomicity, retries and conflicts; migration; filters, snapshot protection, retirement/purge and recovery; OTel setup/failure behavior; troubleshooting. Remote publish/OIDC/RBAC must be identified as deferred, not documented as v1 requirements.

Document pkg6repo/pkg6recv and the final reviewed command set, avoiding the overloaded obsolete-package interface. Contributor architecture remains in the repository (ADRs and component documentation); distinguish existing behavior from proposals. Exact man-page sections, build/install pipeline and documentation publishing location remain implementation work. Record the agreed decision in an ADR before closing #30.

The command audit #40 determines the final CLI reference.

These decisions supersede conflicting earlier scope below. This update records maintainer decisions, not implementation or test completion.

Earlier brief and context

## Maintainer decisions — 2026-09-22 Use an mdBook operator guide PLUS installed CLI man pages. Man pages must follow illumos voice, structure, section conventions and formatting; raw generated clap help is not sufficient without editorial review. Use the local illumos man pages as reference. Guide minimum: IPS/SMF installation and upgrades/config preservation; direct and reverse-proxy TLS; ACME HTTP-01 and Cloudflare/Gandi DNS-01; single certificate owner; .p5p import handoff, atomicity, retries and conflicts; migration; filters, snapshot protection, retirement/purge and recovery; OTel setup/failure behavior; troubleshooting. Remote publish/OIDC/RBAC must be identified as deferred, not documented as v1 requirements. Document pkg6repo/pkg6recv and the final reviewed command set, avoiding the overloaded obsolete-package interface. Contributor architecture remains in the repository (ADRs and component documentation); distinguish existing behavior from proposals. Exact man-page sections, build/install pipeline and documentation publishing location remain implementation work. Record the agreed decision in an ADR before closing #30. The command audit #40 determines the final CLI reference. These decisions supersede conflicting earlier scope below. This update records maintainer decisions, not implementation or test completion. <details> <summary>Earlier brief and context</summary> </details>