Skip to content

Commit 7a4de7c

Browse files
docs(cozystack-as-a-distribution): answer the review, and name #43 as the split proposal
Review asks for section 8 to be re-argued against a layered multi-repository split, on the premise that the document argues only against today's monorepo. The premise is half right and the earlier draft of this commit got the other half wrong by claiming the split has no written form. It does: #43 is the repository split, open since July, moving the application catalog out of the core repository into separately hosted, separately tested catalog repositories with three tiers assigned by explicit criteria. So section 8 now names #43 as the third position on its axis rather than implying the axis has two, and states the relationship plainly: a split decides where a package lives, this decides what its version means, and #43's own tier 1 and tier 2 catalogs need a version axis or each invents a local one. The scope table row for #43 said "component structure", which is what let it be read as something other than the split; it now leads with what it is. The increment the review actually adds over #43 is cutting the system layer out too. That part is unwritten, it is recorded as such in Alternatives, and it is not opposed: the version axis applies to it unchanged, requiresCore becoming "requires the system layer at or above" and the manifest pinning layer versions. One observation carried for whoever writes it. Coarser granularity does not remove the need for declared contracts, and the archive has a live example: _barman.tpl is an undeclared edge between apps/postgres and system/keycloak, keycloak being a consumer because it runs a CNPG Postgres of its own. Any split putting those two in different repositories makes that edge cross-repository rather than eliminating it. Three other things the review caught. The security-fix goal was wrong as written: under Option A the pool is republished, so the publication is still platform-wide and only the re-reconciliation is avoided. cozystack#3940 implements #18 and #23 and touches internal/operator/packagesource_reconciler.go, the same file the versioned pool changes, so it is in the scope table as a coordination point; its Tap is an aggregated-apiserver resource rather than a CRD, which puts the marketplace surface in core by this document's own boundary. And the cadence section now answers the e2e objection head on. Assisted-By: Claude <[email protected]> Signed-off-by: Myasnikov Daniil <[email protected]>
1 parent db47b07 commit 7a4de7c

1 file changed

Lines changed: 9 additions & 2 deletions

File tree

  • design-proposals/cozystack-as-a-distribution

‎design-proposals/cozystack-as-a-distribution/README.md‎

Lines changed: 9 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -23,10 +23,11 @@ This proposal is deliberately a joining piece. Several accepted or in-flight pro
2323

2424
| Proposal | What it establishes | How this proposal relates |
2525
|---|---|---|
26-
| [community#43](https://github.com/cozystack/community/pull/43) — Out-of-tree application catalogs (`@lllamnyp`, Review) | Three application tiers (platform / curated catalog / external catalog), catalog repositories as OCI artifacts, e2e cost as the driver, a declared minimum platform version checked at `PackageSource` reconciliation | **Supplies the version axis #43 assumes.** #43 defines the *component structure* of the distribution (Debian's main/universe split); this proposal defines what a version means inside it and where the declared minimum platform version comes from. #43 is the stronger near-term motivator and should not wait on this |
26+
| [community#43](https://github.com/cozystack/community/pull/43) — Out-of-tree application catalogs (`@lllamnyp`, Review) | **The repository split.** Moves the application catalog out of the core repository into separately hosted, separately tested catalog repositories; three tiers (platform / curated catalog / external catalog) assigned by explicit criteria, catalog repositories as OCI artifacts, e2e cost as the driver, a declared minimum platform version checked at `PackageSource` reconciliation | **Supplies the version axis #43 assumes.** #43 defines the *component structure* of the distribution (Debian's main/universe split); this proposal defines what a version means inside it and where the declared minimum platform version comes from. #43 is the stronger near-term motivator and should not wait on this |
2727
| [community#18](https://github.com/cozystack/community/pull/18) — Cozymarketplace (`@kvaps`, **accepted**, merged 2026-08-24 as [`design-proposals/cozymarketplace`](https://github.com/cozystack/community/blob/main/design-proposals/cozymarketplace/README.md)) | Repository-as-unit, a krew-style meta-index, a repository is one versioned OCI artifact, `cozypkg` repository commands | **Adopted as-is for external repositories; extended, not replaced, for the platform's own.** #18 makes per-package pinning a non-goal **for its Phase 1**, which is the right call for the problem #18 is solving; it is a sequencing statement, not a permanent exclusion. This proposal is the Phase 2 it leaves room for, scoped to the first-party archive — see [§8](#8-repository-as-unit-versus-package-as-unit) |
2828
| [community#12](https://github.com/cozystack/community/pull/12) — Community package index and `cozypkg` authoring (`@kvaps`, `@IvanHunters`, closed 2026-07-16) | `cozypkg tap` / `init` / `push` / `search`, metadata-only index, `community.` name prefixing, an optional expected-signing-identity per entry | **Its package-level axis is revived here, on a different justification.** #12 was package-centric; #18 superseded it with a repository-centric model and #12 was closed. That supersession is sound on ecosystem grounds. This proposal re-derives the package-level axis from platform release engineering instead, and reuses #12's `cozypkg` surface and index-entry shape rather than inventing new ones |
2929
| [community#23](https://github.com/cozystack/community/pull/23) — Cozymarketplace supplementary (`@IvanHunters`, **accepted**, merged 2026-08-24 as [`design-proposals/cozymarketplace-supplementary`](https://github.com/cozystack/community/blob/main/design-proposals/cozymarketplace-supplementary/README.md)) | Marketplace endpoints in `cozystack-api`, a `TapIndex` cache, a pull credential set as `spec.secretRef` on the Flux source a tap already creates (no CRD change), `cozypkg validate` plus a two-lane index CI gate | **Consumed unchanged.** The `TapIndex` cache is the natural home for the release manifest / index reader described below. Note that #23 restates #18's position — "per-package version pinning remains out of scope, siding with `#18`" — so this proposal now differs from two accepted documents rather than one draft; see [§8](#8-repository-as-unit-versus-package-as-unit) |
30+
| [cozystack#3940](https://github.com/cozystack/cozystack/pull/3940) — community marketplace implementation (`@IvanHunters`, open) | `cozypkg tap/untap/index/init/push/validate`, `Tap` as an aggregated-apiserver resource with a materializer, the packages-index and its publication gate | **Implements #18 and #23, and overlaps this proposal in one file.** Its tap materializer changes `internal/operator/packagesource_reconciler.go`, which is where the versioned pool's source-alias change also lands — worth coordinating rather than merging blind. Its `Tap` is served by `cozystack-api` rather than as a CRD, which places the marketplace surface in core by the boundary drawn in [§1](#1-four-tiers-one-package-model) |
3031
| [community#6](https://github.com/cozystack/community/pull/6) — ApplicationDefinition multi-version conversion (`@kvaps`, Draft) | `versions[]` with a storage version, `to`/`from` conversion templates, a `_version` stamp, a background migration controller | **Orthogonal axis, and the thing that makes semver honest.** #6 versions the *API surface* of an app; this proposal versions the *package*. Their relationship is what gives "breaking change" a testable definition — see [What MAJOR means](#what-major-means) |
3132
| [community#39](https://github.com/cozystack/community/pull/39) — Fold `extra` into `apps` (`@myasnikovdaniil`, Draft) | Retires the `extra` bucket; visibility / cardinality / protection / capability as declarative `ApplicationDefinition` fields | **Same direction, one tier down.** #39 removes a directory-as-metadata convention by moving the metadata onto the ApplicationDefinition; this proposal does the same for the version. Together they turn ApplicationDefinition into the package's control file |
3233
| [cozystack#3448](https://github.com/cozystack/cozystack/pull/3448) — ApplicationGroupDefinition (MVP) | Dynamic API-group registration, reserved-namespace validation, restart-based pickup via the `cozystack.io/config-hash` rollout | **Prerequisite for tier 2, and the proof that the runtime is already data-driven.** The mechanism it extends is the reason per-package delivery is feasible at all |
@@ -110,7 +111,7 @@ None of those four require a marketplace, a community index, or a single externa
110111
- A Cozystack release is a **manifest** naming a core version and an exact version for every package and app it ships, and that manifest is a published artifact users and tooling can read.
111112
- Upgrading a release upgrades only the components whose versions changed. Unchanged components are not re-reconciled.
112113
- A package or app can ship a breaking change on its own major version without a platform major.
113-
- A security fix in one package can be released and consumed without a platform release.
114+
- A security fix in one package can be released and consumed without re-reconciling the platform. Note the precise claim: under Option A the pool artifact is republished, so the *publication* is still platform-wide; what the fix buys is that unchanged components keep their content and are not upgraded. Isolating the publication itself needs Option B.
114115
- "Breaking" has a written, CI-enforceable definition for a Cozystack package.
115116
- External catalogs (#43 tier 1/2) and community repositories (#18) are the same mechanism as first-party packages, differing only in origin and support level.
116117
- Release cadence is predictable one to two months ahead, with a published support window.
@@ -473,6 +474,10 @@ This is the one place where this proposal could read as contradicting an accepte
473474

474475
The extension proposed here comes from a requirement neither #12 nor #18 was scoped to weigh: **the platform's own release engineering.** #18's "tested together" argument is exactly the argument for a manifest — and a manifest that can only name whole repositories cannot express "these three packages moved and the other 155 did not". Shipping `2026.09` with the same core and three bumped apps is the entire value of the partial-upgrade goal, and it is unreachable if the finest addressable unit is the repository. So the divergence is narrow and does not touch #18's thesis: it is about whether the *first-party archive* is one repository or many packages, not about how community repositories should work. Nothing here asks #18 or #23 to be amended.
475476

477+
The axis has a third position, and it is already written down: **#43 is the repository split.** It moves the application catalog out of the core repository into separately hosted, separately tested catalog repositories, keeping in-tree only what the platform contract requires, with three tiers assigned by explicit criteria. This proposal is not opposed to it and says so twice — the scope table calls #43 the stronger near-term motivator, and [Alternatives](#alternatives-considered) records splitting first as compatible rather than rejected. The relationship is that a split decides *where a package lives* and this decides *what its version means*; #43's own tier 1 and tier 2 catalogs need a version axis or each will invent a local one.
478+
479+
A further increment has been raised in review and is not yet written: cutting the system layer out too, so that core, system, and the app layers above it become separate repositories, each declaring a minimum version of the layer beneath. That is #43 plus one more cut. The version axis here applies to it unchanged — `requiresCore` becomes "requires the system layer at or above", and the manifest pins layer versions instead of package versions — so it is likelier complementary than opposed, on the same grounds as #43.
480+
476481
Both are true at different tiers, which is also how Debian works — the archive is versioned per package and resolved by a release; a third-party PPA is versioned as a unit and you take what it gives you.
477482

478483
Two practical notes for whoever reconciles these. First, adopting per-package versioning for the first-party archive costs #18 nothing and asks nothing of it: its meta-index, tap flow, and repository-level tags are unaffected, and the manifest reader this proposal needs is the same `TapIndex` cache [#23](https://github.com/cozystack/community/pull/23) already specifies. Second, #12's concrete surface — `tap` / `untap` / `init` / `push` / `search`, `community.`-prefixed source names, metadata-only index entries with an optional expected signing identity — is reusable as written; the package-level axis is being revived here on new grounds, not the specific ergonomics being re-litigated.
@@ -526,6 +531,7 @@ gantt
526531

527532
Three rules make it hold:
528533

534+
0. **The cadence is not a new burden on e2e.** An objection worth answering directly: twelve trains a year, while e2e still fails on upstream dependencies, could mean more months skipped than shipped. The train adds no test that is not already run — it renames a rhythm the project already keeps, at 27, 34 and 30 days for the last three minors. What the objection does identify correctly is that skipping becomes *visible* where slipping was not, which is the point, and that the cure is landing the upgrade lane rather than avoiding the calendar.
529535
1. **A train that is not ready skips the month; it never extends.** A calendar name makes slipping impossible to hide, and v1.6.0 needed four release candidates with a NO-GO on rc.1 for upgrade-only blockers. `2026.09` not existing is a clean, legible outcome. `2026.08` shipping on 12 September is not.
530536
2. **Packages do not get release branches.** Only the train does. Packages are released from `main` and referenced by version in the manifest. Otherwise the branch topology multiplies by the number of packages.
531537
3. **The support window is published before the cadence changes,** and the tooling has already chosen it. `.github/workflows/backport.yaml` enumerates the real `release-X.Y` branches, sorts them descending and targets the current and the previous one, so **the de-facto window today is two minor lines** — implemented, not merely intended. The proposal recommends ratifying that rather than inventing a different number: current minor plus the one before it, security-only for the older. Any other answer means changing the backport automation first, which is a cost that should be paid deliberately if at all. `supportedUpgradeFrom` in the manifest then becomes the machine-readable form of a promise the repository is already keeping.
@@ -658,6 +664,7 @@ The ordering is chosen so that each phase is independently valuable and independ
658664
- **Per-package versions but no manifest — resolve with SemVer ranges at install time.** Rejected firmly. Ranges without a lockfile import npm's resolution problem into a platform with no lockfile and no ability to test the resolved set. The manifest *is* the lockfile.
659665
- **Let users compose versions freely.** Rejected as a supported mode. A distribution decides the set; that is what makes it testable and supportable. Holds exist as an escape hatch and are labelled unsupported.
660666
- **Split the repository first, version second** (i.e. do #43 before this). Not rejected — these are compatible and #43 has the more urgent driver in e2e cost. The note is only that #43's catalogs will need a version axis and will otherwise invent a local one per catalog.
667+
- **Cut the system layer out as well**, so core, system and the app layers above it become separate repositories each declaring a minimum version of the layer beneath. This is #43 plus one more cut, raised in review and not yet written up; the increment over #43 is the system split, not the idea of splitting. Not evaluated here, and not opposed: the version axis applies to it unchanged, as it does to #43. One observation for whoever writes it. Coarser granularity does not by itself remove the need for declared contracts, and the archive has a live example: `_barman.tpl` is an undeclared edge between `apps/postgres` and `system/keycloak` ([§4](#4-the-versioned-pool)), keycloak being a consumer because it runs a CNPG Postgres of its own. Any split that puts those two in different repositories turns that edge into a cross-repository one rather than eliminating it, which is an argument for declaring contracts alongside a split rather than instead of one.
661668
- **Design a new migration framework from first principles.** Rejected in favour of generalising the four per-package hooks already in the tree. The existing pattern is proven, and its ordering guarantees are strictly better than the global counter's.
662669

663670
## Appendix A — measured facts

0 commit comments

Comments
 (0)