Decide the documentation format, location and minimum content for the server release

toasterson commented

2026-09-19 19:58:56 +00:00

Owner

Part of #24

Preserved snapshot support promise — 2026-09-22

Maintainer decision: selected historical ISO snapshots must support maintaining the historical system, not merely booting/installing and upgrading to current Hipster. Users must be able to install additional packages and repair installed packages while retaining that snapshot's original version constraints. Selected snapshots remain protected indefinitely under the agreed retention policy.

Consequences for design and acceptance:

Inventorying only packages already installed in the ISO root filesystem is insufficient. Reconstruct and preserve a usable historical package set, including compatible additional packages, relevant incorporation metadata, dependencies, manifests and payloads. Record provenance/ISO hashes and report unavailable historical content explicitly rather than claiming complete reconstruction.
Packages required for the supported snapshot must remain discoverable to the legacy OpenIndiana pkg5 solver, not just retrievable by an exact-FMRI HTTP request. Design a usable snapshot catalog/view if needed; endpoint/layout mechanics are delegated to engineering and must be validated against local pkg5.
The earlier newest-only incorporation proposal is subordinate to this support promise. Do not remove or hide metadata needed for historical maintenance unless the snapshot view preserves the required semantics and native tests prove it works.
Import exclusions conflicting with the protected historical set still fail preflight and require explicit KDL keep exceptions. Retirement/purge must preserve the full protected snapshot set and shared payload references. Main-catalog hiding must not make a supported snapshot unusable.
Acceptance: from selected historical ISO-installed clients (Hipster approximately 2020 onward), install a package absent from the original image and repair installed content without forcing a move to current package constraints. Also validate the supported update path separately. Use the real local OpenIndiana pkg5 implementation and retain evidence.

This settles the product-level snapshot promise. Reconstruction, snapshot catalog design and validation remain engineering work, not completed functionality.

Configurable retirement and KDL policy — 2026-09-22

Latest maintainer direction:

Retirement must be enable/disable configurable, and its timing must be configurable rather than hard-coded to three months. The maintainer subsequently set the default policy interval to 12 months, superseding the earlier three-month default. Both inactivity and post-hide grace intervals default to 12 months and remain configurable. Earlier three-month references below are historical and superseded.
The import policy file uses KDL, superseding earlier text/JSON alternatives. Regex exclusions and exact-FMRI keep exceptions remain the intended rules: import unmatched packages, explicit keeps override exclusions, invalid patterns or unresolved protected-dependency conflicts fail preflight. Provide explicit proposed exceptions for the operator to add to the KDL file.
Remaining design mechanics are delegated to engineering; do not repeatedly seek maintainer approval for schema spelling, parser choices, CLI spelling or ordinary implementation details. Preserve all agreed semantics.

Engineering defaults/constraints to carry into the design (defaults selected here under that delegation, not independently quoted maintainer decisions): retirement is opt-in/disabled by default; disabling pauses policy-driven retirement without purging content or automatically restoring hidden versions. Continue serving hidden exact-FMRI content. Keep access tracking separately durable. Manual purge remains an explicit operator action with retention, snapshot and dependency checks; enabling retirement must never enable automatic purge. Document configuration effects and validate durations/rules before any mutation.

Still require evidence rather than assumptions: actual local pkg5 behavior, snapshot dependency closure, safe catalog replacement, and historical-client compatibility. No implementation or runtime validation is claimed by this decision update.

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.

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

Earlier brief and context

Question

Three milestone tickets ask for documentation (server, repo-management CLIs, components). Decide what "documented" means for v1 so the writing can be sliced.

Grill on:

Format and home: an mdbook under docs/book/ published by Solstice CI, plain Markdown in doc/, man pages generated from clap, or rustdoc for the library plus a short ops guide?
Audience split: operators (install, configure pkg6depotd.kdl, SMF, TLS, telemetry, RBAC), publishers (how to get a token, publish, archives), contributors (architecture, docs/ai/).
Minimum content for v1 per ticket (#6 server, #9 pkg6repo/pkg6recv, #20 components) and what can be generated (CLI reference from clap, config reference from the KDL structs).
Where CONTEXT.md and ADRs fit for contributors.

Record the outcome as a short ADR and turn it into tickets for #6, #9, #20.

Links

Informs #6
Informs #9
Informs #20

Part of #24 ## Preserved snapshot support promise — 2026-09-22 Maintainer decision: selected historical ISO snapshots must support maintaining the historical system, not merely booting/installing and upgrading to current Hipster. Users must be able to install additional packages and repair installed packages while retaining that snapshot's original version constraints. Selected snapshots remain protected indefinitely under the agreed retention policy. Consequences for design and acceptance: - Inventorying only packages already installed in the ISO root filesystem is insufficient. Reconstruct and preserve a usable historical package set, including compatible additional packages, relevant incorporation metadata, dependencies, manifests and payloads. Record provenance/ISO hashes and report unavailable historical content explicitly rather than claiming complete reconstruction. - Packages required for the supported snapshot must remain discoverable to the legacy OpenIndiana pkg5 solver, not just retrievable by an exact-FMRI HTTP request. Design a usable snapshot catalog/view if needed; endpoint/layout mechanics are delegated to engineering and must be validated against local pkg5. - The earlier newest-only incorporation proposal is subordinate to this support promise. Do not remove or hide metadata needed for historical maintenance unless the snapshot view preserves the required semantics and native tests prove it works. - Import exclusions conflicting with the protected historical set still fail preflight and require explicit KDL keep exceptions. Retirement/purge must preserve the full protected snapshot set and shared payload references. Main-catalog hiding must not make a supported snapshot unusable. - Acceptance: from selected historical ISO-installed clients (Hipster approximately 2020 onward), install a package absent from the original image and repair installed content without forcing a move to current package constraints. Also validate the supported update path separately. Use the real local OpenIndiana pkg5 implementation and retain evidence. This settles the product-level snapshot promise. Reconstruction, snapshot catalog design and validation remain engineering work, not completed functionality. ## Configurable retirement and KDL policy — 2026-09-22 Latest maintainer direction: - Retirement must be enable/disable configurable, and its timing must be configurable rather than hard-coded to three months. The maintainer subsequently set the default policy interval to 12 months, superseding the earlier three-month default. Both inactivity and post-hide grace intervals default to 12 months and remain configurable. Earlier three-month references below are historical and superseded. - The import policy file uses KDL, superseding earlier text/JSON alternatives. Regex exclusions and exact-FMRI keep exceptions remain the intended rules: import unmatched packages, explicit keeps override exclusions, invalid patterns or unresolved protected-dependency conflicts fail preflight. Provide explicit proposed exceptions for the operator to add to the KDL file. - Remaining design mechanics are delegated to engineering; do not repeatedly seek maintainer approval for schema spelling, parser choices, CLI spelling or ordinary implementation details. Preserve all agreed semantics. Engineering defaults/constraints to carry into the design (defaults selected here under that delegation, not independently quoted maintainer decisions): retirement is opt-in/disabled by default; disabling pauses policy-driven retirement without purging content or automatically restoring hidden versions. Continue serving hidden exact-FMRI content. Keep access tracking separately durable. Manual purge remains an explicit operator action with retention, snapshot and dependency checks; enabling retirement must never enable automatic purge. Document configuration effects and validate durations/rules before any mutation. Still require evidence rather than assumptions: actual local pkg5 behavior, snapshot dependency closure, safe catalog replacement, and historical-client compatibility. No implementation or runtime validation is claimed by this decision update. ## 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. These decisions supersede conflicting earlier scope below. This update records maintainer decisions, not implementation or test completion. <details> <summary>Earlier brief and context</summary> ## Question Three milestone tickets ask for documentation (server, repo-management CLIs, components). Decide what "documented" means for v1 so the writing can be sliced. Grill on: - Format and home: an mdbook under `docs/book/` published by Solstice CI, plain Markdown in `doc/`, man pages generated from clap, or rustdoc for the library plus a short ops guide? - Audience split: operators (install, configure `pkg6depotd.kdl`, SMF, TLS, telemetry, RBAC), publishers (how to get a token, publish, archives), contributors (architecture, `docs/ai/`). - Minimum content for v1 per ticket (#6 server, #9 pkg6repo/pkg6recv, #20 components) and what can be generated (CLI reference from clap, config reference from the KDL structs). - Where `CONTEXT.md` and ADRs fit for contributors. Record the outcome as a short ADR and turn it into tickets for #6, #9, #20. ## Links - Informs #6 - Informs #9 - Informs #20 </details>

toasterson added this to the Release 1 (server only) milestone

2026-09-19 19:58:56 +00:00

toasterson added the

wayfinder:grilling

label

2026-09-19 19:58:56 +00:00

toasterson added a new dependency

2026-09-19 19:59:16 +00:00

#25 Define what 'v1.0 server release' must include and its acceptance criteria

toasterson added a new dependency

2026-09-19 19:59:39 +00:00

#6 Document the server

toasterson added a new dependency

2026-09-19 19:59:41 +00:00

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

toasterson added a new dependency

2026-09-19 19:59:42 +00:00

#20 Document Components

toasterson referenced this issue

2026-09-19 19:59:46 +00:00

Wayfinder map: Release 1 (server only) #24

forge referenced this issue

2026-09-22 12:11:21 +00:00

V1: audit repository CLI semantics and remove overloaded obsolete-package #40

forge referenced this issue

2026-09-22 12:11:57 +00:00

Document the server #6

forge referenced this issue

2026-09-22 12:12:03 +00:00

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

forge referenced this issue

2026-09-22 12:12:09 +00:00

Document Components #20

forge referenced this issue

2026-09-23 07:16:40 +00:00

WIP: Build tagged release candidates and an illumos IPS depot package #43

forge commented

2026-09-23 07:26:25 +00:00

Progress: draft PR #43 adds an illumos-style pkg6depotd(8) man page, packaged sample KDL, IPS operator README and release-process documentation. Local mandoc lint and packaged-config tests passed. The full mdBook and remaining command man pages are still outstanding; this ticket remains open.

forge commented

2026-09-23 10:23:17 +00:00

Integrated in PR #46 at 48f8b64: the operator mdBook now covers installation, import, retirement, TLS/ACME, telemetry and release operations. The IPS manifest stages illumos-style pkg6repo(1), pkg6-policy(5), pkg6depotd(8) and pkg6repo-retire(8) pages. Local book checks pass (18/0); the tagged OpenIndiana package job will verify all four pages are installed, render with native man(1), and disappear on uninstall. Keep this ticket open until that native package gate passes.

Integrated in PR #46 at `48f8b64`: the operator mdBook now covers installation, import, retirement, TLS/ACME, telemetry and release operations. The IPS manifest stages illumos-style pkg6repo(1), pkg6-policy(5), pkg6depotd(8) and pkg6repo-retire(8) pages. Local book checks pass (18/0); the tagged OpenIndiana package job will verify all four pages are installed, render with native man(1), and disappear on uninstall. Keep this ticket open until that native package gate passes.

toasterson commented

2026-09-27 13:13:34 +00:00

Author

Owner

Resolution

Decided 2026-09-22 with the maintainer and recorded in ADR-005 (Accepted on PR #54) and the map: an mdBook operator guide under docs/book/ (install, configuration, importing, historical imports, retention, serving, TLS, telemetry, release) plus installed illumos-style man pages (pkg6repo(1), pkg6-policy(5), pkg6depotd(8), pkg6repo-retire(8)) shipped in the IPS package; contributor architecture stays in the repository (docs/, ADRs, CONTEXT.md). The native package gate that verifies the pages install and render is build work under #6/#9/#20, which this ticket no longer blocks.

## Resolution Decided 2026-09-22 with the maintainer and recorded in **ADR-005** (Accepted on PR #54) and the map: an mdBook operator guide under `docs/book/` (install, configuration, importing, historical imports, retention, serving, TLS, telemetry, release) **plus** installed illumos-style man pages (`pkg6repo(1)`, `pkg6-policy(5)`, `pkg6depotd(8)`, `pkg6repo-retire(8)`) shipped in the IPS package; contributor architecture stays in the repository (`docs/`, ADRs, `CONTEXT.md`). The native package gate that verifies the pages install and render is build work under #6/#9/#20, which this ticket no longer blocks.

toasterson closed this issue

2026-09-27 13:13:36 +00:00

toasterson referenced this issue

2026-09-27 13:14:15 +00:00

Wayfinder map: Release 1 (server only) #24