agentic-soc-platform/docs/release-runbook.md

Release Runbook

This runbook is the agent protocol for preparing and publishing ASP releases. The user should be able to start a normal release with only:

Release v<version>, title is <title>.

The release is standardized by deploy/release-manifest.json and deploy/release_tool.py. Do not rely on memory or a manual checklist for deterministic version updates.

Release configuration source

deploy/release-manifest.json is the current release configuration source.

Required fields:

Field	Purpose
version	Release version without v, for example 0.5.1.
title	Human release title, for example Winter is Coming.
previousVersion	Previous release version without v; default this from the latest remote v* tag unless the user gives a different base.
baseTag	Optional override for the commit range base; default is v<previousVersion>.
releaseDocSlug	Stable release notes slug under asp-doc/docs/<lang>/release/. Auto-fill from version/title unless the user requests another slug.
releaseDocsBaseUrl	Public release docs base URL, currently https://asp.viperrtp.com/release.
surfaces	Named release surfaces managed by deploy/release_tool.py.

Current managed surfaces:

Surface	Managed files
cli_version	cli/pyproject.toml
compose_env_example	deploy/asp-compose/.env.example
quickstart_deployment_docs	asp-doc/docs/zh/asp/quick-start/deployment/index.md, asp-doc/docs/en/asp/quick-start/deployment/index.md
quickstart_upgrade_docs	asp-doc/docs/zh/asp/quick-start/upgrade/index.md, asp-doc/docs/en/asp/quick-start/upgrade/index.md
release_notes_pages	asp-doc/docs/zh/release/<slug>/index.md, asp-doc/docs/en/release/<slug>/index.md
vitepress_nav	asp-doc/docs/.vitepress/config/zh.ts, asp-doc/docs/.vitepress/config/en.ts

deploy/release-docs.json is no longer used. The Release workflow resolves the release notes URL from the manifest.

Standard release flow for agents

1. Inspect state

   • Check main repo status and branch.

   • Check asp-doc status and branch.

   • If asp-doc is missing or uninitialized, ask the user to run or approve:

     git submodule update --init asp-doc
     

   • Check latest remote release tags and whether the requested tag already exists.

   • Check whether asp-cli==<version> already exists on PyPI, because PyPI versions are immutable.

   • Identify unrelated dirty files and do not include them in release commits.

2. Update the manifest

   • Normalize the requested tag v<version> to manifest version.
   • Set title from the user request.
   • Infer previousVersion from the latest remote v* tag unless the user provided another base.
   • Auto-fill releaseDocSlug from version/title unless the user requested a specific slug.
   • Keep releaseDocsBaseUrl and the standard surfaces list unless there is a deliberate release-process change.

3. Prepare deterministic files

   • Run:

     python deploy/release_tool.py prepare
     

   • This updates CLI version, compose image tags, deployment/upgrade docs generated blocks, release page skeletons, and VitePress changelog nav.

   • Do not manually edit generated release blocks except by changing the manifest or tool.

4. Write release notes

   • Generate candidate highlights from commits between baseTag/v<previousVersion> and the planned release commit.

   • Ask the user once for optional Developer Notes raw material or curated highlights. It is acceptable for the user to provide nothing.

   • Write the Chinese release page first:

     asp-doc/docs/zh/release/<releaseDocSlug>/index.md
     

   • Then write the matching English page:

     asp-doc/docs/en/release/<releaseDocSlug>/index.md
     

   • Keep Chinese and English pages structurally aligned.

   • Do not put the full release narrative in the GitHub Release body; the workflow creates a minimal body that links to the docs page and lists downloads/images.

5. Validate before commits

   • Run:

     python deploy/release_tool.py check
     python deploy/release_tool.py show
     

   • Build/check CLI package metadata when practical:

     cd cli
     uv build
     uvx twine check dist/*
     uv run asp --version
     cd ..
     

   • Run the compose package validation path when practical:

     bash ./deploy/package-asp-compose.sh --version <version> --output-dir dist-release-check
     test -f dist-release-check/asp-compose.tar.gz
     tar -tzf dist-release-check/asp-compose.tar.gz >/dev/null
     rm -rf dist-release-check/unpacked
     mkdir -p dist-release-check/unpacked
     tar -xzf dist-release-check/asp-compose.tar.gz -C dist-release-check/unpacked
     

   • Clean temporary validation output:

     rm -rf dist-release-check
     rm -rf cli/dist
     

   • Do not run VitePress docs build unless the user explicitly asks.

   • Frontend changes do not require npm build validation unless the user explicitly asks.

6. Commit in the correct order

   • Commit release docs changes inside asp-doc.
   • Commit main repository release-preparation changes, including:
     • deploy/release-manifest.json
     • deploy/release_tool.py if changed
     • workflow/runbook changes if changed
     • cli/pyproject.toml
     • deploy/asp-compose/.env.example
     • the asp-doc submodule pointer
   • Do not include unrelated local files.
   • Include the required Co-authored-by trailer when creating commits.

7. Ask for publish permission

   • Before pushing commits or tags, ask for explicit permission.
   • Confirm the tag name v<version>.
   • For the first CLI release in a new environment, confirm PyPI Trusted Publishing is configured for project asp-cli, workflow release.yml, environment pypi.

8. Publish

   • Push the asp-doc release notes commit.

   • Push the main repository release-preparation commit.

   • Create an annotated tag:

     git tag -a v<version> -m "v<version> - <title>"
     

   • Push the tag:

     git push origin v<version>
     

   • Monitor the GitHub Actions Release workflow.

9. Post-release checks

   • Confirm the GitHub Release exists.
   • Confirm asp-compose.tar.gz is attached.
   • Confirm backend and frontend images exist in GHCR with the version tag.
   • Confirm asp-cli==<version> exists on PyPI.
   • Confirm the release body links to the expected release notes URL from python deploy/release_tool.py show.
   • Confirm the public docs site has or will deploy the release page.

Naming conventions

• Git tag: v<version>, for example v0.5.1.
• Manifest version and CLI PyPI package version: no v, for example 0.5.1.
• Release doc slug: explicit and stable after publishing, usually generated from version/title, for example 0_5_1_Winter_is_Coming.
• GitHub Release title: v<version> - <title>.
• Compose archive: asp-compose.tar.gz.
• GHCR image tags:
  • ghcr.io/<owner>/<repo>/asp-backend:<version>
  • ghcr.io/<owner>/<repo>/asp-frontend:<version>
  • latest is also pushed for non-dev versions by the Docker workflow.

Generated blocks

The quick-start deployment and upgrade pages contain generated blocks:

<!-- release:<name>:start -->
...
<!-- release:<name>:end -->

Only deploy/release_tool.py prepare should update these blocks. If check reports a stale generated block, update the manifest if needed and rerun prepare.

Release notes writing rules

Release notes are generated by the agent, not by release_tool.py. The tool only creates missing page skeletons and checks titles/nav/paths.

Default Chinese structure:

# <version> - <title>

## 新功能

## 优化

## 修复

## 部署和发布工程

## 升级说明

## 开发者笔记

Default English structure:

# <version> - <title>

## New Features

## Improvements

## Fixes

## Deployment and Release Engineering

## Upgrade Notes

## Developer Notes

Developer Notes may include background, motivation, opinions, lessons learned, tradeoffs, and complaints when the user provides them. Preserve the user's intent and tone, but organize fragmented material into readable paragraphs. Do not invent personal feelings or motivations.

Failure handling

• If prepare or check fails, fix the manifest or managed source files before committing.
• If validation fails before the tag is pushed, fix the release-preparation commit before creating the tag.
• If the tag has not been pushed, delete and recreate the local tag after fixing the target commit.
• If the tag has been pushed and the Release workflow fails, inspect failed job logs before changing anything.
• Prefer rerunning failed workflow jobs for transient infrastructure failures.
• If a pushed tag points to the wrong commit or release inputs are wrong, stop and ask before deleting or recreating the remote tag.
• If GitHub Release creation succeeds but docs are wrong, update docs and let the public docs deploy; update the GitHub Release body only if the minimal link/download/image body is wrong.
• If publish-cli fails because PyPI Trusted Publishing is not configured, configure the trusted or pending publisher for project asp-cli, workflow release.yml, environment pypi, then rerun the failed job.
• If publish-cli fails because the PyPI version already exists, do not try to overwrite it. Stop and decide whether to cut a new patch version.

Minimal prompt for future releases

The user can start with:

Release v<version>, title is <title>.

The agent should infer the base from the latest release tag, prepare deterministic files from the manifest, ask once for optional release-note context, and ask again only for publish permission.