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:
@@ -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
|
||||
|
||||
|
||||
@@ -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`
|
||||
|
||||
Reference in New Issue
Block a user