Skip to content

Commit 16c5642

Browse files
CrazyBaranclaude
CrazyBaran
and
claude
committed
docs(extensions): distinguish version-driven offers from advisory staleness
Copilot review round 4 on #4351: two documentation spots still described `specify extension update` as comparing "versions only" / "purely" by semver, with unbumped content reporting "Up to date" forever - wording this PR itself made stale when it added the content-hash check. Clarify in extensions/EXTENSION-DEVELOPMENT-GUIDE.md (Versioning) and the .github/scripts/check_extension_version_bump.py module docstring that update offers remain version-driven - a bump is still required for automatic delivery - while the content-hash check on bundled extensions is only an advisory stale-content warning pointing at a manual --force reinstall. Wording only; no behavior change. Refs #4345 Assisted-by: Claude Code (model: claude-fable-5, autonomous) Co-Authored-By: Claude Fable 5 <[email protected]>
1 parent edb30a4 commit 16c5642

2 files changed

Lines changed: 20 additions & 12 deletions

File tree

‎.github/scripts/check_extension_version_bump.py‎

Lines changed: 9 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,15 @@
11
#!/usr/bin/env python3
22
"""Fail a PR that changes bundled extension content without a version bump.
33
4-
`specify extension update` decides whether an installed extension needs
5-
updating purely by comparing the semver in `extensions/catalog.json`
6-
against the installed copy's registered version. Content changes that
7-
ship without a version bump therefore never reach existing installs:
8-
every one of them reports "Up to date" forever (#4345).
4+
Update offers from `specify extension update` are version-driven: an
5+
extension is offered (and installed) only when the semver in
6+
`extensions/catalog.json` exceeds the installed copy's registered
7+
version. A content change shipped without a version bump is therefore
8+
never delivered automatically (#4345). The command's content-hash check
9+
can detect such unbumped drift on bundled extensions, but only as an
10+
advisory stale-content warning pointing at a manual `--force` reinstall —
11+
a bump is what makes a change actually reach existing installs, and this
12+
guard is what makes the bump non-optional.
913
1014
This check enforces two invariants on the extensions listed in
1115
`extensions/catalog.json`:

‎extensions/EXTENSION-DEVELOPMENT-GUIDE.md‎

Lines changed: 11 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -620,13 +620,17 @@ See the [Extension Publishing Guide](EXTENSION-PUBLISHING-GUIDE.md) for detailed
620620
- **MAJOR**: Breaking changes
621621
- **MINOR**: New features
622622
- **PATCH**: Bug fixes
623-
- **Bump on every content change**: `specify extension update` compares
624-
versions only, so a content change shipped without a version bump never
625-
reaches already-installed copies. For the bundled extensions in this
626-
repository this is enforced by CI (`extension-version-guard.yml`): a PR
627-
that changes files under `extensions/<id>/` must also bump that
628-
extension's `extension.yml` version and keep `extensions/catalog.json`
629-
in sync.
623+
- **Bump on every content change**: update offers from `specify extension
624+
update` are version-driven, so a content change shipped without a
625+
version bump is never delivered automatically to already-installed
626+
copies. For bundled extensions the command can detect such unbumped
627+
drift and flag it as stale content, but that is only an advisory
628+
warning pointing at a manual `--force` reinstall — a bump is still
629+
required for the change to be offered and installed. For the bundled
630+
extensions in this repository the bump is enforced by CI
631+
(`extension-version-guard.yml`): a PR that changes files under
632+
`extensions/<id>/` must also bump that extension's `extension.yml`
633+
version and keep `extensions/catalog.json` in sync.
630634

631635
### Security
632636

0 commit comments

Comments
 (0)