From c07ca0767e2e64537119cc3eeea88dbb7c163752 Mon Sep 17 00:00:00 2001 From: Defame1297 Date: Wed, 16 Sep 2026 10:33:35 +0000 Subject: [PATCH] docs(kyberforge): stop apm-workflow assuming root package versions The root apm.yml packages[] entries no longer carry version:, and a version there is a silent override that --check-versions does not catch. configure.md and marketplace.md now name the package's own apm.yml as the single source and drop version: from the examples. Co-Authored-By: Claude Opus 5 (1M context) --- .../apm-workflow/references/configure.md | 13 ++++++------ .../apm-workflow/references/marketplace.md | 21 ++++++++++++------- 2 files changed, 20 insertions(+), 14 deletions(-) diff --git a/plugins/kyberforge/.apm/skills/apm-workflow/references/configure.md b/plugins/kyberforge/.apm/skills/apm-workflow/references/configure.md index 808f9c2..e4d45d2 100644 --- a/plugins/kyberforge/.apm/skills/apm-workflow/references/configure.md +++ b/plugins/kyberforge/.apm/skills/apm-workflow/references/configure.md @@ -53,12 +53,13 @@ output changes.** Two triggers, not one: The version belongs to the package, not to the repo: editing `plugins/foo/.apm/` never bumps `plugins/bar/apm.yml`. -Under a `per_package` strategy the same number is also carried in the catalog's -`marketplace.packages[]` entry, so both copies move together in the same commit. The catalog's own -version follows a separate rule — see `references/marketplace.md`. `apm pack --check-versions` -fails the push when a package's version disagrees with the configured strategy, so a bump applied -in only one of the two places is caught, but a bump skipped in both is not: nothing infers intent -from a content diff. +Under a `per_package` strategy this `version:` is the single source: when a catalog's +`marketplace.packages[]` entry omits `version:`, `apm pack` reads it from the package's `apm.yml`. +Do not restate it there. A `version:` on the entry is an override, not a copy — it silently wins in +the compiled `marketplace.json`, and `apm pack --check-versions` still reports `[matches]` when it +disagrees with the package's own number, so drift between the two is never caught. Set one only +when an override is the intent. A skipped bump is not caught either: nothing infers intent from a +content diff. The catalog's own version follows a separate rule — see `references/marketplace.md`. ## Dependency reference forms diff --git a/plugins/kyberforge/.apm/skills/apm-workflow/references/marketplace.md b/plugins/kyberforge/.apm/skills/apm-workflow/references/marketplace.md index 68fa29f..b305868 100644 --- a/plugins/kyberforge/.apm/skills/apm-workflow/references/marketplace.md +++ b/plugins/kyberforge/.apm/skills/apm-workflow/references/marketplace.md @@ -35,7 +35,6 @@ marketplace: - name: plugin-a description: ... source: ./packages/plugin-a - version: 1.0.0 ``` This local-path `source:` form IS valid — `apm marketplace check` and `apm pack` both accept it — even though the `package add` CLI subcommand cannot create it for you. Use `apm marketplace package add` only for packages hosted at a remote git ref; for local packages, edit the YAML directly. @@ -63,12 +62,17 @@ The local-filesystem and `file://` forms need no hosted registry or network acce marketplace: versioning: { strategy: per_package } packages: - - { name: plugin-a, source: ./packages/plugin-a, version: 2.0.0 } - - { name: plugin-b, source: ./packages/plugin-b, version: 0.1.0 } + - { name: plugin-a, source: ./packages/plugin-a } + - { name: plugin-b, source: ./packages/plugin-b } ``` Without this block, the default versioning strategy ties every listed package to the marketplace/root version. +With it, each entry's version comes from its package's own `apm.yml`. An entry may also set +`version:`, but that is an override: it silently wins in the compiled `marketplace.json`, and +`apm pack --check-versions` does not flag the mismatch. Omit it unless an override is intended — +see `references/configure.md`. + ## Bumping the catalog's own version (repo policy) The section above is apm's *mechanic* — how per-package versions are declared and how @@ -79,11 +83,12 @@ earned it: - **Minor** when a `marketplace.packages[]` entry is added or removed. The catalog's contents changed — a consumer resolving it now gets a different set of installable packages. -- **Patch** when only `marketplace:`-block fields change and the set of packages is unchanged: the - catalog description, owner, `build:`/`outputs:` config, or an existing entry's `version:`, - description, or category. The catalog describes the same packages; only its metadata moved. An - entry's `version:` is the most frequent of these by far — under `per_package` it moves here every - time any package bumps (see `references/configure.md`), and that alone earns the catalog patch. +- **Patch** when the set of packages is unchanged but what the catalog publishes moved: a + `marketplace:`-block field (the catalog description, owner, `build:`/`outputs:` config, or an + existing entry's description or category), or any listed package's own `apm.yml` `version:`. The + most frequent trigger by far is the package bump. The root entry carries no `version:`, but the + compiled `marketplace.json` publishes each package's version, so a package bump alone changes the + catalog and alone earns the patch — made in the same commit (see `references/configure.md`). Keep the root `apm.yml`'s top-level `version:` in step with `marketplace.version`. They are separate keys — the top-level one is not inherited into the compiled `marketplace.json`, but `apm audit`