feat(standards): MR-based tag strategy + repository inventory (registry://repos)

Versioning standard now documents the MR flow: bump pyproject.toml/VERSION and promote CHANGELOG in the MR (referencing the version/tag, not a commit id), merge/squash, then tag the resulting commit. Adds the agent-assisted tagging procedure (wait for the go-ahead, find the version-bump commit, tag only it, ask the user to push) to both the reference page and the releasing wiki runbook. Adds the repo inventory (src/repos.json -> mcp/repos.json), the registry://repos resource + list_repos tool, the 15_repository_inventory lib page, and two MCP prompts: compliance (remediate repos) and release (agent tagging).
This commit is contained in:
2026-10-15 14:39:21 +05:30
parent df03f41771
commit 5971f26c08
36 changed files with 2107 additions and 94 deletions

View File

@@ -14,7 +14,7 @@
<link rel="prev" href="../10_drone_pipelines/">
<link rel="next" href="../12_genericity_matrix/">
<link rel="next" href="../15_repository_inventory/">
<link rel="icon" href="../assets/images/favicon.png">
@@ -556,6 +556,30 @@
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#tagging-strategy-mr-based" class="md-nav__link">
<span class="md-ellipsis">
Tagging strategy (MR-based)
</span>
</a>
<nav class="md-nav" aria-label="Tagging strategy (MR-based)">
<ul class="md-nav__list">
<li class="md-nav__item">
<a href="#agent-assisted-tagging" class="md-nav__link">
<span class="md-ellipsis">
Agent-assisted tagging
</span>
</a>
</li>
</ul>
</nav>
</li>
<li class="md-nav__item">
@@ -599,6 +623,28 @@
<li class="md-nav__item">
<a href="../15_repository_inventory/" class="md-nav__link">
<span class="md-ellipsis">
Repository Inventory
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../12_genericity_matrix/" class="md-nav__link">
@@ -725,6 +771,30 @@
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#tagging-strategy-mr-based" class="md-nav__link">
<span class="md-ellipsis">
Tagging strategy (MR-based)
</span>
</a>
<nav class="md-nav" aria-label="Tagging strategy (MR-based)">
<ul class="md-nav__list">
<li class="md-nav__item">
<a href="#agent-assisted-tagging" class="md-nav__link">
<span class="md-ellipsis">
Agent-assisted tagging
</span>
</a>
</li>
</ul>
</nav>
</li>
<li class="md-nav__item">
@@ -809,8 +879,9 @@ and tag contract is exactly what those two CI shapes consume.</p>
<li><strong>Tag = version.</strong> The git tag is bare SemVer (<code>0.0.6</code>), no <code>v</code> prefix, and
it MUST match the version file byte-for-byte. The Drone guard fails the
build otherwise — this is what stops a tag from silently publishing nothing.</li>
<li><strong>A release is a tag.</strong> Bump the version file, promote the changelog, commit,
tag, push. Everything else is automated by Drone.</li>
<li><strong>A release is a tag, created after the change is merged.</strong> The version bump
and the changelog promotion travel inside the merge request (MR); the tag is
added on the merged commit and pushed. See <a href="#tagging-strategy-mr-based">Tagging strategy</a>.</li>
<li><strong>Never reuse a tag.</strong> If a release is wrong, cut a new patch version.</li>
</ol>
<h3 id="pre-10-0yz">Pre-1.0 (0.y.z)</h3>
@@ -867,17 +938,50 @@ one open <code>[Unreleased]</code> section with the change categories that apply
version heading and clear it.</li>
</ul>
<hr />
<h2 id="tagging-strategy-mr-based">Tagging strategy (MR-based)</h2>
<p>The release version is known while the change is still a merge request, so the
bump travels with the change and only the tag is added afterwards:</p>
<ol>
<li><strong>In the MR</strong> — set the intended release version: <code>version</code> in
<code>pyproject.toml</code> (or the <code>VERSION</code> file) to <code>x.y.z</code>, and promote the
changelog (below). Changelog entries and link references name the
<strong>version/tag</strong>, never a commit id.</li>
<li><strong>Merge or squash</strong> the MR into <code>main</code>.</li>
<li><strong>Create the tag</strong> <code>x.y.z</code> on the resulting commit (the merge/squash commit).</li>
<li><strong>Push the tag</strong> (<code>git push origin x.y.z</code>) — Drone builds the release.</li>
</ol>
<p>Because the version bump is inside the tagged commit, the guard's
<code>tag == version</code> check can only fail if the wrong commit was tagged.</p>
<h3 id="agent-assisted-tagging">Agent-assisted tagging</h3>
<p>The agent neither authors nor merges the MR, and never tags before the merge.
After the user confirms the MR is merged/squashed and says to proceed:</p>
<ol>
<li><strong>Wait</strong> for that explicit go-ahead.</li>
<li>Find the commit that introduced the version bump:</li>
<li>packages:
<code>git log -S 'version = "x.y.z"' -n 1 --format='%H %s' -- pyproject.toml</code></li>
<li>services:
<code>git log -S 'x.y.z' -n 1 --format='%H %s' -- VERSION</code></li>
<li>Confirm that commit's version file equals <code>x.y.z</code>, then tag <strong>only</strong> that
commit, lightweight and bare: <code>git tag x.y.z &lt;sha&gt;</code>.</li>
<li><strong>Do not push.</strong> Ask the user to push the tag: <code>git push origin x.y.z</code>.</li>
</ol>
<hr />
<h2 id="release-checklist">Release checklist</h2>
<ol>
<li>Confirm the quality gate is green on <code>main</code>.</li>
<li>Move every <code>[Unreleased]</code> entry under the new version heading with today's
date (<code>## [x.y.z] - YYYY-MM-DD</code>); restore an empty <code>[Unreleased]</code> on top.</li>
<li>Add the two compare-link references at the bottom of the changelog.</li>
<li>Set the version file: <code>pyproject.toml</code> (<code>version = "x.y.z"</code>) or <code>VERSION</code>.</li>
<li>Commit: <code>chore(release): x.y.z</code>.</li>
<li>Tag: <code>git tag x.y.z</code> and push the tag (<code>git push origin x.y.z</code>).</li>
<li>Watch Drone: Type A publishes the wheel/sdist, Type B builds and deploys the
image. Both first assert <code>tag == version</code>.</li>
<li>Confirm the quality gate is green and <code>main</code> is up to date.</li>
<li>In the MR: move every <code>[Unreleased]</code> entry under the new version heading with
the target date (<code>## [x.y.z] - YYYY-MM-DD</code>); restore an empty <code>[Unreleased]</code>
on top.</li>
<li>In the MR: add the two compare-link references at the bottom of the
changelog, naming the version/tag (never a commit id).</li>
<li>In the MR: set the version file — <code>pyproject.toml</code> (<code>version = "x.y.z"</code>) or
<code>VERSION</code> — to the intended release version.</li>
<li>Merge or squash the MR into <code>main</code>.</li>
<li>Create the tag on the resulting commit: lightweight <code>git tag x.y.z</code>.</li>
<li>Push the tag (<code>git push origin x.y.z</code>). Watch Drone: Type A publishes the
wheel/sdist, Type B builds and deploys the image; both first assert
<code>tag == version</code>.</li>
<li>Do not reuse the tag if the run fails — fix and cut <code>x.y.(z+1)</code>.</li>
</ol>
<hr />
@@ -891,7 +995,7 @@ Drone guard turns that silent no-op into a hard failure.</p>
<hr />
<h2 id="related">Related</h2>
<ul>
<li><a href="../10_drone_pipelines/">10 – Drone Pipelines</a> · <a href="../01_build_recipe/">01 – Build Recipe</a> · <a href="../13_library_registry/">13 – Library Registry</a></li>
<li><a href="../10_drone_pipelines/">10 – Drone Pipelines</a> · <a href="../15_repository_inventory/">15 – Repository Inventory</a> · <a href="../01_build_recipe/">01 – Build Recipe</a> · <a href="../13_library_registry/">13 – Library Registry</a></li>
</ul>