chore: drop the duplicated package descriptions from root apm.yml

Why: for a local-path marketplace entry, apm treats a root description: as
an override of the package's own apm.yml, reported only at verbose level,
so the "two copies stay identical" rule had no enforcement. Same fix as
2def060 made for version:.

Implementation Notes:
- All six root copies matched their package apm.yml before removal; the
  compiled marketplace.json descriptions are unchanged.
- apm-workflow references now scope the "omit it" advice to local-path
  entries: on a remote entry, version: is the semver range that selects
  the tag, and version: or ref: is required.

Impact: ADR-0021 amended; the package apm.yml is the single source.

ADR: 0021
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
This commit is contained in:
2026-09-16 11:24:22 +00:00
parent c5d43b4d63
commit 398515bcad
4 changed files with 53 additions and 20 deletions

View File

@@ -53,13 +53,19 @@ 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 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`.
Under a `per_package` strategy this `version:` is the single source for a local-path
(`source: ./…`) catalog entry: when that `marketplace.packages[]` entry omits `version:`,
`apm pack` reads it from the package's `apm.yml`. Do not restate it there. On a local entry a
`version:` 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.
`description:` behaves the same way: a local entry that omits it publishes the package `apm.yml`'s
`description`, and one that sets it silently overrides it. A remote entry is different. There,
`version:` is the semver range that selects which git tag to resolve, and a remote entry must carry
`version:` or `ref:`. Its `description:`, when set, is the published text.
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

View File

@@ -68,10 +68,13 @@ marketplace:
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`.
With it, each local-path (`source: ./…`) entry's version comes from its package's own
`apm.yml`, and so does its `description`. A local entry may also set `version:` or `description:`,
but either one is an override: it silently wins in the compiled `marketplace.json`, and
`apm pack --check-versions` does not flag a version mismatch. Omit both unless an override is
intended — see `references/configure.md`. A remote entry is different: its `version:` is the semver
range that selects the git tag to resolve (matched through the entry's `tag_pattern`, else
`build.tagPattern`), not an override, and the entry must set `version:` or `ref:`.
## Bumping the catalog's own version (repo policy)
@@ -86,9 +89,10 @@ earned it:
- **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`).
most frequent trigger by far is the package bump. When entries omit `version:` (the recommended
local form), the compiled `marketplace.json` still 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`