Skip to content

RELEASING-docs-checklist.md

Latest commit

 

History

History
148 lines (129 loc) · 9.02 KB

RELEASING-docs-checklist.md

File metadata and controls

148 lines (129 loc) · 9.02 KB
Raw

Release documentation checklist

Every release MUST refresh the version/release references below. The library code ships from metaobjectsdev/metaobjects, but documentation and the public sites live in three repos and drift independently — a version bump is not "done" until this whole list is walked.

Companion to RELEASING.md (npm/TS) and RELEASING-java.md (Maven Central). Two version lines, one release: npm / NuGet / PyPI carry the shared number (1.0.0 at the 1.0 cut) and Maven Central carries the same minor.patch on npm major + 7 (8.0.0). Do not hardcode either major anywhere — the previous 0.x / 7.x spelling of this sentence outlived its truth by exactly one release.

Tip: the fastest way to not miss anything is to grep the previous version across each repo (see Quick scan) — this list is the map, the grep is the safety net.

A. This repo — metaobjectsdev/metaobjects

  • README.md — per-port version rows (npm + Maven Central).
  • CHANGELOG.md — add the release entry.
  • CLAUDE.md — the ## Status section (version line + "Last refreshed" date).
  • docs/llms/llms.txt — the "Shipping at <npm> … and <maven> …" line, the ## Implementations (npm … / Maven Central …) header, the per-port version lines, and the install snippets.
  • docs/llms/llms-full.txt — same version touch-points as llms.txt.
  • docs/ports/typescript.md — npm version + install snippet.
  • docs/ports/typescript-client.md — npm version (if referenced).
  • docs/ports/csharp.md — the <PackageReference … Version="…"/> snippets.
  • docs/ports/java.md — Maven <version> + artifact list.
  • docs/ports/kotlin.md — Maven <version>.
  • docs/ports/python.md — PyPI version + pip install.
  • docs/features/extending-with-providers.md — no version edit any more. Its "Cross-port parity status" table reads Shipped for all five ports with no version scope, so there is no "as of <ver>" marker left to refresh (checked at the 1.0 cut). Re-add one here only if parity ever becomes version-scoped again.
  • docs/RELEASING.md / docs/RELEASING-java.md — the "currently <ver>" notes.
  • Grep the docs for "UNRELEASED" / "on main, shipping in the next". A capability documented before it ships carries that hedge on purpose, and it becomes a lie the moment the cut lands. agent-context/skills/metaobjects-authoring/SKILL.md carries one today for the Kotlin builder (#365) — flip it to the shipped version and regenerate fixtures/agent-context-conformance/ in the same commit.
  • .github/workflows/publish-*.yml — no version edits by design. All four publish workflows read the version from the committed manifest (package.json / pom / Directory.Build.props / pyproject.toml), so none hardcodes one. Re-check only if someone adds a version string back; the publish-csharp.yml workflow_dispatch description carried one until 0.21.6 and had silently drifted seven releases stale.
  • agent-context/ — NO version edits on a bump, by design. The meta init LLM-context source is version-agnostic: Maven examples use ${metaobjects.version} and there are no hardcoded npm versions. Only touch it when a feature or API changed (not a version number), and re-verify its accuracy when you do.

B. The websites — separate sibling repos

metaobjectsdev/metaobjectsdev.github.io → metaobjects.dev (GitHub Pages, content under www/)

Nothing on this list is a version edit any more, and that is the point — every version-bearing byte the site serves is copied or injected at deploy time from THIS repo, pinned to the newest npm-line release tag. What the release owes the site is a push, not an edit. Confirm rather than change:

  • www/llms.txt / www/llms-full.txt — gitignored there, copied from this repo's docs/llms/ at deploy. Fix them here (§A), never in the site repo.

  • www/assess.md — gitignored there, built at deploy from the pinned tag by node scripts/build-assess-prompt.mjs --out <path>, which inlines the skill's references/ files into one prompt. A bare copy of agent-context/skills/metaobjects-fit-assessment/SKILL.md is not the hosted form any more: the capability sheet and the JSON contract live in references/. The site deploy must call the script when the tag has it (and may keep the old sed copy for tags that do not). Fix the content here. Required before the first release tag that carries the split skill becomes the pinned one — in the site repo's .github/workflows/deploy.yml, replace the SKILL=… if block that writes www/assess.md with:

    ```bash
if [ -f scripts/build-assess-prompt.mjs ]; then
  # tags with the split skill: the script is the only complete form
  if node scripts/build-assess-prompt.mjs --out /tmp/assess.md && [ -s /tmp/assess.md ]; then
    cp /tmp/assess.md "$GITHUB_WORKSPACE/www/assess.md"
  else
    echo "::error::metaobjects $TAG could not build assess.md" >&2
    exit 1
  fi
else
  # older tags: the skill is one file, so the old copy is complete
  SKILL=agent-context/skills/metaobjects-fit-assessment/SKILL.md
  if [ -f "$SKILL" ] && sed -n '/^# /,$p' "$SKILL" | sed '/^<!--$/,/^-->$/d' > /tmp/assess.md && [ -s /tmp/assess.md ]; then
    cp /tmp/assess.md "$GITHUB_WORKSPACE/www/assess.md"
  else
    echo "::warning::metaobjects $TAG has no usable fit-assessment skill — /assess.md will 404."
  fi
fi
```

A script that exists but fails must NOT fall back to the `sed` copy: on these tags that
copy is missing the capability sheet and the JSON contract. It fails the deploy
instead (`exit 1`), so a release never publishes a site whose `/assess.md` is missing
or incomplete; only the older-tag branch, which has no script to fail, still warns.

  • www/index.html and every other page — the four registry coordinates plus metamodel are injected into any element carrying data-registry="…", and the derived counts (fixtures, corpora, baseTypes) into any element carrying data-count="…", both from examples/showcase/site-payload.json. The numbers in the committed HTML are placeholders; editing them changes nothing that ships.

  • A NEW placeholder key must reach a release tag BEFORE the page that uses it. The pages deploy on push from the site repo; the payload and the injector come from the pinned release tag. So a page carrying a data-registry/data-count key that the pinned tag's payload has never heard of makes the injector throw — and that step sits before "Upload artifact", so it takes down the whole site deploy, unrelated prose edits included. Order: land the key in this repo → cut a release → then add the placeholder to the page. Never the reverse.

  • The tag pin resolves to the release you just cut. deploy.yml walks the release tags newest-first and takes the one whose server/typescript/packages/cli/package.json is versioned as the tag — that is what identifies the npm line, since the legacy JVM-only v7.x tags still sort above it. Read the pinned to metaobjects vX.Y.Z line in the deploy log; a wrong pin publishes a stale site with every step green.

  • Preview exactly what a deploy would render, without touching the site checkout: bun run site:preview --site <site-repo>/www --strict.

  • Deploys automatically via .github/workflows/deploy.yml on push to the default branch. A push IS a deploy — there is no staging.

metaobjectsdev/metaobjects.com → metaobjects.com (Eleventy → Cloudflare Pages)

  • Version-agnostic by design — the marketing copy carries no version numbers, so a version bump needs no change here. Only revise on a messaging change.
  • Build/deploy: npm run deploy (Eleventy build → wrangler pages deploy dist), or its .github/workflows/deploy.yml.

Quick scan

From the release branch, grep the previous version to catch anything this list misses:

# this repo (metaobjects) — the only repo where a version is hand-written
grep -rn "<previous-npm-version>\|<previous-maven-version>" README.md CHANGELOG.md CLAUDE.md docs/

# the coordinates the site will serve — one file, five values
jq .registries examples/showcase/site-payload.json

Any hit outside CHANGELOG.md / historical docs/superpowers/** / spec/decisions/** (which intentionally preserve old versions) is a doc that still needs revising.

Do not grep the site repo's www/. Its version numbers are placeholders and its mirrors are gitignored build output, so that grep reports hits nobody should fix and misses the one thing that can actually be wrong — which release tag the deploy pins to.