feat(standards): drop the site CI variant + require changelog reconciliation before release

- Remove the push-triggered build-and-deploy-site pipeline and every "site"
  reference; Type B is now a single tag-triggered service pipeline
  (service-docker.yaml).
- Inventory now covers packages + the auth-server service only (repos.json
  11 -> 9; docs/mcp are no longer part of the standard).
- Versioning standard: reconcile [Unreleased] against the last tag before
  promoting, and always show proposed entries to the user for approval.
- Update registry.py compliance/release text and list_repos types, build.py
  component descriptions, and rebuild the MCP bundle + lib/wiki HTML.
This commit is contained in:
2026-10-17 00:41:52 +05:30
parent e33a6d6704
commit 104bf3eb1e
28 changed files with 234 additions and 353 deletions

View File

@@ -556,6 +556,21 @@
</span>
</a>
<nav class="md-nav" aria-label="The changelog">
<ul class="md-nav__list">
<li class="md-nav__item">
<a href="#reconcile-before-releasing" class="md-nav__link">
<span class="md-ellipsis">
Reconcile before releasing
</span>
</a>
</li>
</ul>
</nav>
</li>
<li class="md-nav__item">
@@ -771,6 +786,21 @@
</span>
</a>
<nav class="md-nav" aria-label="The changelog">
<ul class="md-nav__list">
<li class="md-nav__item">
<a href="#reconcile-before-releasing" class="md-nav__link">
<span class="md-ellipsis">
Reconcile before releasing
</span>
</a>
</li>
</ul>
</nav>
</li>
<li class="md-nav__item">
@@ -842,7 +872,7 @@
<h1 id="versioning-changelog">Versioning &amp; Changelog</h1>
<h2 id="summary">Summary</h2>
<p>Every Aetos artifact — library, service, or site — is versioned with
<p>Every Aetos artifact — library or service — is versioned with
<a href="https://semver.org/spec/v2.0.0.html">Semantic Versioning</a> and documents its
releases in a <a href="https://keepachangelog.com/en/1.1.0/">Keep a Changelog</a> file.
The <strong>version file is the source of truth</strong>, the <strong>git tag must equal it</strong>, and
@@ -867,7 +897,7 @@ and tag contract is exactly what those two CI shapes consume.</p>
<td><code>check-version</code> also reads it to skip duplicates</td>
</tr>
<tr>
<td>Service / site (Docker)</td>
<td>Service (Docker)</td>
<td><code>VERSION</code> file at the repo root</td>
<td>one line, <code>x.y.z</code>; the service <strong>reads</strong> it (build-arg) — never hardcode the version</td>
</tr>
@@ -934,16 +964,35 @@ one open <code>[Unreleased]</code> section with the change categories that apply
<li>Categories: <strong>Added</strong>, <strong>Changed</strong>, <strong>Deprecated</strong>, <strong>Removed</strong>, <strong>Fixed</strong>,
<strong>Security</strong>. Omit empty categories.</li>
<li>Security fixes get their own entry even if the change is otherwise a bug fix.</li>
<li>Keep <code>[Unreleased]</code> current: add an entry in the same change that introduces
the behaviour, not later.</li>
<li>The <code>[Unreleased]</code> heading is never renamed; copy its content into the new
version heading and clear it.</li>
</ul>
<h3 id="reconcile-before-releasing">Reconcile before releasing</h3>
<p><code>[Unreleased]</code> is a <strong>draft, not the source of truth</strong>. It is only trustworthy
when it was maintained alongside each change; a long-running branch or a change
that skipped the changelog leaves it stale, so it can silently under-report a
release. Verify it against the change before you promote:</p>
<ol>
<li>List what actually changed since the last release:
<code>git log &lt;last-tag&gt;..HEAD</code> and <code>git diff --stat &lt;last-tag&gt;..HEAD</code>.</li>
<li>Compare that against <code>[Unreleased]</code>; add an entry for every user-facing change
that is missing.</li>
<li><strong>Always show the proposed additions to the user and wait for approval</strong>
before promoting. If an entry is ambiguous, ask rather than guess.</li>
</ol>
<p>Only then promote. Never cut a release with a known gap between the diff and the
changelog.</p>
<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
<li><strong>In the MR</strong> — reconcile <code>[Unreleased]</code> against the change (see
<a href="#reconcile-before-releasing">Reconcile before releasing</a>) and get the user's
approval for any additions. Then 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>
@@ -970,8 +1019,11 @@ After the user confirms the MR is merged/squashed and says to proceed:</p>
<h2 id="release-checklist">Release checklist</h2>
<ol>
<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>
<li>In the MR: reconcile <code>[Unreleased]</code> against the change being released —
<code>git log &lt;last-tag&gt;..HEAD</code> and <code>git diff --stat &lt;last-tag&gt;..HEAD</code> — add any
missing user-facing entries, and get the user's approval for the additions.
Then move every <code>[Unreleased]</code> entry under the new version heading with the
target date (<code>## [x.y.z] - YYYY-MM-DD</code>) and 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>