diff --git a/.github/instructions/testing.instructions.md b/.github/instructions/testing.instructions.md index e42523e58..8e18cc873 100644 --- a/.github/instructions/testing.instructions.md +++ b/.github/instructions/testing.instructions.md @@ -11,12 +11,12 @@ definitions come from `decisions/0007-release-publication-flow.md`. ## Identify the class first -| Class | Repos | What it is | -| ----- | ----------------------------------- | ------------------------------ | -| 1 | `wiki`, `src`, `zd` | Continuously deployed artifact | -| 2 | `zunit`, `zsh-lint`, packaged `zsh` | Versioned tool/package | -| 3 | `zi`, most plugins/annexes | Git-consumed source | -| 4 | `.github` | Meta/infrastructure | +| Class | Repos | What it is | +| ----- | -------------------------------------------- | ------------------------------ | +| 1 | `wiki`, `src`, `zd` | Continuously deployed artifact | +| 2 | `zunit`, `zsh-lint`, `zpmod`, packaged `zsh` | Versioned tool/package | +| 3 | `zi`, most plugins/annexes | Git-consumed source | +| 4 | `.github` | Meta/infrastructure | ## Baseline (every repo) @@ -35,9 +35,10 @@ definitions come from `decisions/0007-release-publication-flow.md`. - **Class 1 — deployed:** the build must pass on the development branch before deploy. Wiki: ESLint + Stylelint + production build. `zd`: Docker build matrix. `src`: installer/loader validation. Add CodeQL where a supported language exists. -- **Class 2 — versioned tools:** a **full functional suite is required and gates - release tags**. ZUnit for Zsh tools; `go test` for the `zsh-lint` Go CLI. Never - cut a `vX.Y.Z` tag from a red commit. +- **Class 2, versioned tools:** a **full functional suite is required on the + exact tag commit and gates release publication**. ZUnit for Zsh tools; + `go test` for the `zsh-lint` Go CLI; the repository-defined full suite for + `zpmod`. Never cut a `vX.Y.Z` tag from a red commit. - **Class 3 — git-consumed:** **validation-only.** Baseline checks plus ZUnit where the plugin ships tests. No release automation, no coverage gate. The bar is "loads and parses cleanly." diff --git a/decisions/0007-release-publication-flow.md b/decisions/0007-release-publication-flow.md index a125bb64b..5819059b6 100644 --- a/decisions/0007-release-publication-flow.md +++ b/decisions/0007-release-publication-flow.md @@ -29,7 +29,8 @@ formalizes. the development branch; deploy via the repo's existing delivery model. No tag-driven changelog/release automation unless a separate packaged artifact appears. -2. **Versioned tools and packages** (`zunit`, `zsh-lint`, packaged `zsh`): +2. **Versioned tools and packages** (`zunit`, `zsh-lint`, `zpmod`, packaged + `zsh`): `main` is continuously validated development output; **annotated semantic tags `vX.Y.Z` are the publication boundary**. User-facing releases are minted only from those tags. @@ -60,6 +61,11 @@ Per-repo application: - **`zsh-lint`** — a Zsh plugin consumed from source, with **no build artifact**. Its release is a tagged GitHub release with generated notes only (no upload). (`zsh-lint#21`.) +- **`zpmod`**: class 2, with annotated `vX.Y.Z` tags created only from reviewed, + green `main` commits. Pages and documentation publish only from reviewed + `main` commits; that continuous documentation surface does not replace the + annotated tag as the versioned release boundary. (`z-shell/.github#497`, + `z-shell/zpmod#70`.) - **packaged `zsh`** — deferred: confirm what it publishes (npm package vs. metadata) before wiring a release, since the artifact determines the steps. (`zsh#8`.) @@ -94,3 +100,6 @@ Per-repo application: - `z-shell/zunit` `.github/workflows/release.yml` — reference tag-driven flow. - `decisions/0003-conventional-commits.md` — history format this builds on. - Tracker: `zsh-lint#21`, `zsh#8`, `zi#346`. +- [Issue #497](https://github.com/z-shell/.github/issues/497) and + [z-shell/zpmod#70](https://github.com/z-shell/zpmod/issues/70): accepted + `zpmod` classification and owning repository remediation. diff --git a/decisions/0008-branching-model.md b/decisions/0008-branching-model.md index b27e6bf65..57fa4de7d 100644 --- a/decisions/0008-branching-model.md +++ b/decisions/0008-branching-model.md @@ -13,12 +13,13 @@ inconsistency is real, not cosmetic: - Some repos run a `next` → `main` integration flow (`src`, `wiki`, `zi`, `zsh-lint`, `zsh-eza`). -- Others are trunk-based on `main` only (`zd`, packaged `zsh`, +- Others are trunk-based on `main` only (`zd`, packaged `zsh`, `zpmod`, `z-a-meta-plugins`, `zsh-fancy-completions`, `zunit`, `.github`). -An audit on 2026-07-18 found that all listed repositories use `main` as their -GitHub default branch. Only `src`, `wiki`, `zi`, `zsh-lint`, and `zsh-eza` have -a live `next` branch for development or integration. In this ADR, **GitHub +An audit on 2026-07-18 found that all repositories listed at that time use +`main` as their GitHub default branch. Only `src`, `wiki`, `zi`, `zsh-lint`, and +`zsh-eza` have a live `next` branch for development or integration. The accepted +2026-08-14 `zpmod` audit adds `zpmod` as trunk on `main`. In this ADR, **GitHub default branch** and **development branch** are therefore separate concepts. The private meta-workspace catalog (`workspace/repos.yml`) is still out of date. Its @@ -38,25 +39,26 @@ development branch and branch model. The ADR-0007 repository class is an _input_ to the choice because it sets the publication boundary and a default, but it does **not** by itself determine the branch model — repo churn/scale does. Within class 1, `wiki`/`src` use `next` → `main` while `zd` is -trunk-only; within class 2, `zsh-lint` uses `next` while `zunit` is trunk. -Changing a repository's assigned model requires amending this ADR (or a -superseding one), not merely creating or deleting a branch. +trunk-only; within class 2, `zsh-lint` uses `next` while `zunit` and `zpmod` are +trunk-based. Changing a repository's assigned model requires amending this ADR +(or a superseding one), not merely creating or deleting a branch. ### Canonical branch model -| Repo | Class | Branch model | Development branch | Publication boundary | -| ----------------------- | ----- | --------------- | ------------------ | ------------------------ | -| `wiki` | 1 | `next` → `main` | `next` | merge to `main` (deploy) | -| `src` | 1 | `next` → `main` | `next` | merge to `main` (deploy) | -| `zd` | 1 | trunk on `main` | `main` | push to `main` (image) | -| `zunit` | 2 | trunk on `main` | `main` | `vX.Y.Z` tag | -| `zsh-lint` | 2 | `next` → `main` | `next` | `vX.Y.Z` tag | -| packaged `zsh` | 2 | trunk on `main` | `main` | `vX.Y.Z` tag (deferred) | -| `zi` | 3 | `next` → `main` | `next` | `main` is consumable ref | -| `zsh-eza` | 3 | `next` → `main` | `next` | `main` is consumable ref | -| `z-a-meta-plugins` | 3 | trunk on `main` | `main` | `main` is consumable ref | -| `zsh-fancy-completions` | 3 | trunk on `main` | `main` | `main` is consumable ref | -| `.github` | 4 | trunk on `main` | `main` | n/a | +| Repo | Class | Branch model | Development branch | Publication boundary | +| ----------------------- | ----- | --------------- | ------------------ | ----------------------------------------- | +| `wiki` | 1 | `next` → `main` | `next` | merge to `main` (deploy) | +| `src` | 1 | `next` → `main` | `next` | merge to `main` (deploy) | +| `zd` | 1 | trunk on `main` | `main` | push to `main` (image) | +| `zunit` | 2 | trunk on `main` | `main` | `vX.Y.Z` tag | +| `zsh-lint` | 2 | `next` → `main` | `next` | `vX.Y.Z` tag | +| `zpmod` | 2 | trunk on `main` | `main` | `vX.Y.Z` tag; Pages from reviewed `main` | +| packaged `zsh` | 2 | trunk on `main` | `main` | `vX.Y.Z` tag (deferred) | +| `zi` | 3 | `next` → `main` | `next` | `main` is consumable ref | +| `zsh-eza` | 3 | `next` → `main` | `next` | `main` is consumable ref | +| `z-a-meta-plugins` | 3 | trunk on `main` | `main` | `main` is consumable ref | +| `zsh-fancy-completions` | 3 | trunk on `main` | `main` | `main` is consumable ref | +| `.github` | 4 | trunk on `main` | `main` | n/a | The publication-boundary column states the policy, not a complete inventory of live workflow triggers. At the 2026-07-18 audit, `src` and `zd` also had @@ -123,3 +125,6 @@ public factual-reconciliation change. - `runbooks/branch-protection.md` — enforcement checklist for this model. - [Issue #454](https://github.com/z-shell/.github/issues/454) — dated live audit and maintainer decision record. +- [Issue #497](https://github.com/z-shell/.github/issues/497) and + [z-shell/zpmod#70](https://github.com/z-shell/zpmod/issues/70): accepted + `zpmod` classification and owning repository remediation. diff --git a/decisions/0009-testing-ci-strategy.md b/decisions/0009-testing-ci-strategy.md index a7fa8c7a5..fcc0819ad 100644 --- a/decisions/0009-testing-ci-strategy.md +++ b/decisions/0009-testing-ci-strategy.md @@ -60,17 +60,19 @@ rollout status per repository is tracked in issue #454, not restated here. lint and production build, `zd`'s Docker build matrix, and `src`'s installer/loader validation, plus CodeQL where a supported language is present. -2. **Versioned tools and packages** (`zunit`, `zsh-lint`, packaged `zsh`) — a full - functional suite is **required** before a release tag is cut, defined per - tool: `zunit`'s release workflow must run its own native suite on the exact - tag commit before publication, since prior branch checks alone do not prove - the released commit; packaged `zsh`'s gate is metadata/manifest validation - plus a clean disposable install and a startup/version smoke test, all on - the exact tag commit, since metadata-only validation alone is not a - functional suite; `zsh-lint`'s gate is `go test` on the exact tag commit. - Compiled tools additionally run an appropriate SAST control, such as - CodeQL or `gosec`; a release artifact is part of the security surface - governed by `decisions/0010-security-incident-response.md`. +2. **Versioned tools and packages** (`zunit`, `zsh-lint`, `zpmod`, packaged + `zsh`): a full functional suite is **required** before a release tag is cut, + defined per tool: `zunit`'s release workflow must run its own native suite on + the exact tag commit before publication, since prior branch checks alone do + not prove the released commit; `zpmod` must run its repository-defined full + functional suite on the exact tag commit before publication; packaged + `zsh`'s gate is metadata/manifest validation plus a clean disposable install + and a startup/version smoke test, all on the exact tag commit, since + metadata-only validation alone is not a functional suite; `zsh-lint`'s gate + is `go test` on the exact tag commit. Compiled tools additionally run an + appropriate SAST control, such as CodeQL or `gosec`; a release artifact is + part of the security surface governed by + `decisions/0010-security-incident-response.md`. 3. **Git-consumed source** (`zi`, most plugins/annexes) — **validation-only**: the baseline checks above, plus ZUnit where the plugin ships tests. No release automation and no coverage gate; these repos are consumed from source and the @@ -130,3 +132,6 @@ that a ruleset enforces it. - `z-shell/zd` `.github/workflows/test-native.yml` — reusable ZUnit workflow. - [Issue #454](https://github.com/z-shell/.github/issues/454) — dated rollout-gap evidence and maintainer decision record. +- [Issue #497](https://github.com/z-shell/.github/issues/497) and + [z-shell/zpmod#70](https://github.com/z-shell/zpmod/issues/70): accepted + `zpmod` classification and exact-tag test obligation. diff --git a/decisions/0013-repository-settings-baseline.md b/decisions/0013-repository-settings-baseline.md index 148ae092c..f40f31125 100644 --- a/decisions/0013-repository-settings-baseline.md +++ b/decisions/0013-repository-settings-baseline.md @@ -71,7 +71,8 @@ Classes are exactly those defined in table stays readable: 1. **Continuously deployed artifacts** — `wiki`, `src`, `zd` images -2. **Versioned tools and packages** — `zunit`, `zsh-lint`, packaged `zsh` +2. **Versioned tools and packages:** `zunit`, `zsh-lint`, `zpmod`, packaged + `zsh` 3. **Git-consumed source** — `zi`, most plugins and annexes 4. **Meta/infrastructure** — `.github` diff --git a/runbooks/release.md b/runbooks/release.md index b9eaf480a..f256e7fb0 100644 --- a/runbooks/release.md +++ b/runbooks/release.md @@ -36,6 +36,7 @@ Examples likely to fit: - `zunit` - `zsh-lint` +- `zpmod` Policy: