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

toasterson commented

2026-09-19 19:58:45 +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.

V1 administration boundary — 2026-09-22

Maintainer decision: the public HTTP interface is read-only in v1. Imports, retirement/purge and repository administration are available through local commands only. Remote publication and OIDC/RBAC remain deferred.

Apply this boundary to actual registered routes and any web UI: do not expose repository-mutating or administrative operations publicly in v1. Read-only package serving/search remain available. ACME HTTP-01 challenge serving remains supported and is not a repository administration endpoint. Document the local operator/CI script workflow and validate that public HTTP cannot mutate repository state. This records required behavior, not a claim that current routes already enforce it.

Load testing scope correction — 2026-09-22

The maintainer rejected the proposed mandatory 24-hour pre-cutover soak. Sustained-load testing/observation can take place after cutover and is not a v1 release gate. The workload is predominantly file downloads at low concurrency; search is the main query-computation concern highlighted by the maintainer. Do not infer that ingestion/catalog maintenance requires no server computation.

Keep pre-release correctness and targeted functional checks for real OpenIndiana pkg5 clients, search, atomic batch imports, and continuous reads across stable-path catalog rename. OTel failure isolation remains a required behavior. Do not add a mandatory soak duration, synthetic concurrency target, or numeric performance threshold without a new decision. Current oirepo remains the qualitative operational baseline. This supersedes earlier proposed soak/load release gates; it does not authorize production cutover or claim tests have run.

Deployment and load clarification — 2026-09-22

Maintainer-provided target: oirepo6, a zone on the same existing host as oirepo, behind the same reverse proxy. Neither zone has explicit resource limits. This describes the intended deployment; no live host/resource inspection has yet been performed.

The intended eventual role is the main repository host. V1 qualification still uses the separate depot; this does not authorize production cutover. It must serve the existing client population comfortably, with performance comparable to the current service. Traffic is predominantly a few requests at a time, accumulating substantial volume over time, rather than large simultaneous bursts.

For #31/#5, use the current service as the comparative baseline and representative low-concurrency sustained traffic as the workload. Actual request-rate/concurrency distribution and resource consumption still need measurement; no numerical latency/RSS/duration budget has been agreed. Include service behavior during imports/catalog maintenance. Absence of zone caps is not an allocation of the shared host's resources; establish a safe test budget before load generation.

Maintainer decisions — 2026-09-22

V1 proves a separate depot importing the historical split OpenIndiana repositories. The maintainer will provide access; production cutover is a follow-up.
OpenIndiana pkg5 clients from approximately Hipster 2020 onward are mandatory. Select exact old/current ISO fixtures and prove real client operations; OmniOS validation is deferred to v1.2 and is not yet verified.
Preserve local OpenIndiana pkg5 semantics. Use the local OpenIndiana/pkg5 checkout as the compatibility authority rather than assuming Oracle Solaris equivalence.
pkg6 owns the migrated format; legacy files are retained. Reverting requires export or restore, not an assumed in-place pkg5 fallback.
Local imports suffice for v1. One completed multi-package .p5p per CI run is delivered, then CI notifies a script to import it. Entire batch becomes visible atomically. Identical archive retry is a successful no-op; an exact-FMRI content conflict rejects the entire batch.
Authenticated remote publishing, OIDC and publishing RBAC are deferred; no later target release was selected for them.
Repository retirement hides versions from catalogs/search but continues exact-FMRI manifest and payload service. Purge is a second, operator-triggered step with enforced checks. No automatic purge or S3 in v1.
V1 requires traces, metrics and structured logs via OTLP/HTTP; collector outages never block serving/imports. Bounded export queues drop oldest queued records on overflow and count drops. Durable access/retention records are independent.
Both reverse-proxy TLS and direct TLS are required. Direct TLS includes ACME HTTP-01 and DNS-01 for Cloudflare and Gandi, with unattended renewal. In proxy mode the proxy owns TLS/ACME and depot ACME is disabled.
Ship an OpenIndiana IPS package and SMF integration with configuration preservation.
Documentation: mdBook operator guide PLUS installed CLI man pages in illumos voice and format. Contributor architecture stays in the repository.

Still open: exact ISO matrix, performance/concurrency/RSS budgets (#31), deployment resources, detailed retirement edge cases, ADR capture and build-ticket slicing. Keep this decision ticket open until the remaining release acceptance criteria are settled.

Implementation/verification tickets: #38, #39, #40, #41, #42.

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

Earlier brief and context

Question

What must be true before we tag pkg6depotd v1.0? Settle the release scope so every other decision on this map has a boundary.

Grill on:

Which clients must be served: legacy pkg(1) from OpenIndiana hipster and OmniOS? pkg6 itself? Which pkg5 depot API versions (/versions/0 advertised set) are the compatibility contract?
Which repositories: OpenIndiana hipster (size, publisher count), OmniOS core/extra? Is running the production OpenIndiana depot on pkg6depotd a v1 goal or a follow-up?
Feature gates: is authenticated publish mandatory for v1, or can v1 ship read-only plus publish behind a feature flag? Is RBAC required, or is "any valid token with ips:write may publish" enough for the first release? Is OpenTelemetry release-blocking?
Non-functional gates: load-test targets (p95 latency for catalog/manifest/file, memory ceiling on the production repo), supported platforms (illumos x86_64 required, Linux build only?), packaging (IPS package + SMF manifest?), documentation minimum.
What "done" means for each milestone ticket, so that /to-tickets can later slice the build.

Record the outcome as an ADR (docs/ai/decisions/004-...) and update the milestone description.

Links

(none)

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. ## V1 administration boundary — 2026-09-22 Maintainer decision: the public HTTP interface is read-only in v1. Imports, retirement/purge and repository administration are available through local commands only. Remote publication and OIDC/RBAC remain deferred. Apply this boundary to actual registered routes and any web UI: do not expose repository-mutating or administrative operations publicly in v1. Read-only package serving/search remain available. ACME HTTP-01 challenge serving remains supported and is not a repository administration endpoint. Document the local operator/CI script workflow and validate that public HTTP cannot mutate repository state. This records required behavior, not a claim that current routes already enforce it. ## Load testing scope correction — 2026-09-22 The maintainer rejected the proposed mandatory 24-hour pre-cutover soak. Sustained-load testing/observation can take place after cutover and is not a v1 release gate. The workload is predominantly file downloads at low concurrency; search is the main query-computation concern highlighted by the maintainer. Do not infer that ingestion/catalog maintenance requires no server computation. Keep pre-release correctness and targeted functional checks for real OpenIndiana pkg5 clients, search, atomic batch imports, and continuous reads across stable-path catalog rename. OTel failure isolation remains a required behavior. Do not add a mandatory soak duration, synthetic concurrency target, or numeric performance threshold without a new decision. Current oirepo remains the qualitative operational baseline. This supersedes earlier proposed soak/load release gates; it does not authorize production cutover or claim tests have run. ## Deployment and load clarification — 2026-09-22 Maintainer-provided target: `oirepo6`, a zone on the same existing host as `oirepo`, behind the same reverse proxy. Neither zone has explicit resource limits. This describes the intended deployment; no live host/resource inspection has yet been performed. The intended eventual role is the main repository host. V1 qualification still uses the separate depot; this does not authorize production cutover. It must serve the existing client population comfortably, with performance comparable to the current service. Traffic is predominantly a few requests at a time, accumulating substantial volume over time, rather than large simultaneous bursts. For #31/#5, use the current service as the comparative baseline and representative low-concurrency sustained traffic as the workload. Actual request-rate/concurrency distribution and resource consumption still need measurement; no numerical latency/RSS/duration budget has been agreed. Include service behavior during imports/catalog maintenance. Absence of zone caps is not an allocation of the shared host's resources; establish a safe test budget before load generation. ## Maintainer decisions — 2026-09-22 - V1 proves a separate depot importing the historical split OpenIndiana repositories. The maintainer will provide access; production cutover is a follow-up. - OpenIndiana pkg5 clients from approximately Hipster 2020 onward are mandatory. Select exact old/current ISO fixtures and prove real client operations; OmniOS validation is deferred to v1.2 and is not yet verified. - Preserve local OpenIndiana pkg5 semantics. Use the local OpenIndiana/pkg5 checkout as the compatibility authority rather than assuming Oracle Solaris equivalence. - pkg6 owns the migrated format; legacy files are retained. Reverting requires export or restore, not an assumed in-place pkg5 fallback. - Local imports suffice for v1. One completed multi-package .p5p per CI run is delivered, then CI notifies a script to import it. Entire batch becomes visible atomically. Identical archive retry is a successful no-op; an exact-FMRI content conflict rejects the entire batch. - Authenticated remote publishing, OIDC and publishing RBAC are deferred; no later target release was selected for them. - Repository retirement hides versions from catalogs/search but continues exact-FMRI manifest and payload service. Purge is a second, operator-triggered step with enforced checks. No automatic purge or S3 in v1. - V1 requires traces, metrics and structured logs via OTLP/HTTP; collector outages never block serving/imports. Bounded export queues drop oldest queued records on overflow and count drops. Durable access/retention records are independent. - Both reverse-proxy TLS and direct TLS are required. Direct TLS includes ACME HTTP-01 and DNS-01 for Cloudflare and Gandi, with unattended renewal. In proxy mode the proxy owns TLS/ACME and depot ACME is disabled. - Ship an OpenIndiana IPS package and SMF integration with configuration preservation. - Documentation: mdBook operator guide PLUS installed CLI man pages in illumos voice and format. Contributor architecture stays in the repository. Still open: exact ISO matrix, performance/concurrency/RSS budgets (#31), deployment resources, detailed retirement edge cases, ADR capture and build-ticket slicing. Keep this decision ticket open until the remaining release acceptance criteria are settled. Implementation/verification tickets: #38, #39, #40, #41, #42. 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 What must be true before we tag pkg6depotd v1.0? Settle the release scope so every other decision on this map has a boundary. Grill on: - Which clients must be served: legacy `pkg(1)` from OpenIndiana hipster and OmniOS? `pkg6` itself? Which pkg5 depot API versions (`/versions/0` advertised set) are the compatibility contract? - Which repositories: OpenIndiana hipster (size, publisher count), OmniOS core/extra? Is running the *production* OpenIndiana depot on pkg6depotd a v1 goal or a follow-up? - Feature gates: is authenticated publish mandatory for v1, or can v1 ship read-only plus publish behind a feature flag? Is RBAC required, or is "any valid token with `ips:write` may publish" enough for the first release? Is OpenTelemetry release-blocking? - Non-functional gates: load-test targets (p95 latency for catalog/manifest/file, memory ceiling on the production repo), supported platforms (illumos x86_64 required, Linux build only?), packaging (IPS package + SMF manifest?), documentation minimum. - What "done" means for each milestone ticket, so that `/to-tickets` can later slice the build. Record the outcome as an ADR (`docs/ai/decisions/004-...`) and update the milestone description. ## Links - (none) </details>

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

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

toasterson added the

wayfinder:grilling

label

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