feat(standards): add versioning + changelog standard, release templates, and Drone version guard

Add lib page 11 (SemVer contract, pre-1.0 rule, tag==version invariant, Keep a Changelog), the releasing wiki runbook, and canonical release templates (CHANGELOG.md, VERSION). Vendor them into the MCP bundle as templates/release + release.json and expose registry://release with list/get tools. Add a changelog component to the app template. Enforce the tag<->version contract in both Drone shapes: Type A check-version and the backfill loop verify pyproject version; Type B adds a VERSION guard step.
This commit is contained in:
2026-10-15 01:24:25 +05:30
parent a754366901
commit 8cc9631fe7
25 changed files with 625 additions and 10 deletions

View File

@@ -239,6 +239,8 @@ _TEMPLATE_COMPONENTS: list[dict[str, str]] = [
"description": "OpenAPI contract skeleton."},
{"kind": "pyproject", "path": "pyproject.toml", "placeholder": "",
"description": "Packaging + dependency pins."},
{"kind": "changelog", "path": "CHANGELOG.md", "placeholder": "",
"description": "Keep a Changelog file with an [Unreleased] section (versioning standard)."},
{"kind": "dockerfile", "path": "Dockerfile", "placeholder": "",
"description": "API + worker image with private-index wiring."},
{"kind": "dockerignore", "path": ".dockerignore", "placeholder": "",
@@ -412,6 +414,82 @@ def build_drone_templates(folder: Path, dry_run: bool = False) -> None:
f"({len(manifest['components'])} components)")
# ── Release standard bundle ───────────────────────────────────────────────────
# The release artefacts shipped in ``src/templates/release``. One canonical
# changelog (Keep a Changelog + SemVer) and the service version file. See
# standards "11_versioning_and_changelog".
_RELEASE_COMPONENTS: list[dict[str, str]] = [
{"kind": "changelog", "path": "CHANGELOG.md", "placeholder": "",
"description": "Keep a Changelog skeleton: one [Unreleased] section + compare links."},
{"kind": "version-file", "path": "VERSION", "placeholder": "",
"description": "Single-line SemVer source of truth for services and sites."},
]
def build_release_manifest(template_root: Path) -> dict[str, object]:
"""Describe every artefact in the vendored release standard.
Args:
template_root (Path): The vendored ``templates/release`` directory.
Returns:
dict[str, object]: Manifest with the component entries and the
tag == version invariant.
"""
components: list[dict[str, str]] = []
for entry in _RELEASE_COMPONENTS:
rel = entry["path"]
if not (template_root / rel).exists():
raise SystemExit(f"[ERR] release template missing: {rel}")
components.append({
"kind": entry["kind"],
"path": rel,
"placeholder": entry["placeholder"],
"description": entry["description"],
})
return {
"project": "standards",
"template": "templates/release",
"invariant": "git tag == version file (enforced by the Drone guard)",
"components": components,
}
def build_release_templates(folder: Path, dry_run: bool = False) -> None:
"""Vendor ``folder/src/templates/release`` into ``<name>/mcp/templates/release``.
Ships the canonical ``CHANGELOG.md`` and ``VERSION`` in the MCP bundle so an
agent can drop them into a repo, and emits ``release.json`` describing them.
Args:
folder (Path): The hub folder owning ``src/templates/release``.
dry_run (bool): Print the plan without executing.
"""
name = folder.name
src = folder / "src" / "templates" / "release"
if not src.is_dir():
return
out_dir = folder / "mcp" / "templates" / "release"
if dry_run:
print(f"[REL] {name} {src.relative_to(ROOT)}/** -> {out_dir.relative_to(ROOT)}/**")
return
if out_dir.exists():
shutil.rmtree(out_dir)
out_dir.parent.mkdir(parents=True, exist_ok=True)
shutil.copytree(
src, out_dir,
ignore=shutil.ignore_patterns("__pycache__", "*.pyc", ".git"),
)
manifest = build_release_manifest(out_dir)
(folder / "mcp" / "release.json").write_text(
json.dumps(manifest, indent=2, ensure_ascii=False), encoding="utf-8"
)
print(f"[REL] {name} release templates vendored to {out_dir.relative_to(ROOT)}/ "
f"({len(manifest['components'])} components)")
# ── CLI ──────────────────────────────────────────────────────────────────────
@@ -432,6 +510,7 @@ def main() -> None:
build_bundle(folder, dry_run=args.dry_run)
build_templates(folder, dry_run=args.dry_run)
build_drone_templates(folder, dry_run=args.dry_run)
build_release_templates(folder, dry_run=args.dry_run)
build_html(folder, dry_run=args.dry_run)