Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Release Checklist

Use this checklist before tagging or publishing an Yanshi release. The automated checks are enforced by the release gate job in .github/workflows/quality.yml; the remaining items require human judgement.

For release tracking, open .github/ISSUE_TEMPLATE/release.md and link the CI run that passed on the release branch or tag.

CI Coverage

The release gate job requires these automated jobs to pass:

  • cargo fmt
  • cargo clippy
  • package test matrix for yanshi-core, yanshi-tools, yanshi-memory, yanshi-mcp, yanshi-skills, yanshi-agents, and yanshi-cli
  • workspace doc tests
  • selected feature combinations
  • workspace examples compile and no-API smoke tests

The checklist below keeps local parity commands for reproducing CI failures, then lists the manual release review items.

1. Scope

  • Confirm release target, version, and branch.
  • Review RoadMap.md, TODOs.md, and release notes for completed work.
  • Confirm ignored local files such as TODOs.md, target/, and run output directories are not required in the release commit.
  • Review git status --short --ignored and ensure only intentional ignored files remain.

2. Code Quality (CI Covered)

cargo fmt --all -- --check
cargo clippy --workspace --all-targets -- -D warnings
cargo check --workspace --target-dir /tmp/yanshi-target
cargo test --workspace --doc --target-dir /tmp/yanshi-target
  • Formatting passes.
  • Clippy has no warnings.
  • Workspace compile check passes.
  • Workspace doc tests pass.
  • No accidental debug prints, temporary fixtures, or local paths are present.

3. Core Test Matrix (CI Covered)

Run the focused crate matrix first so failures are easy to localize:

cargo test -p yanshi-core --target-dir /tmp/yanshi-target
cargo test -p yanshi-tools --target-dir /tmp/yanshi-target
cargo test -p yanshi-memory --target-dir /tmp/yanshi-target
cargo test -p yanshi-mcp --target-dir /tmp/yanshi-target
cargo test -p yanshi-skills --target-dir /tmp/yanshi-target
cargo test -p yanshi-agents --target-dir /tmp/yanshi-target
cargo test -p yanshi-cli --target-dir /tmp/yanshi-target

Then run the full workspace:

cargo test --workspace --target-dir /tmp/yanshi-target
  • Core workflow/checkpoint tests pass.
  • Tool registry and built-in tool tests pass.
  • MCP protocol, client, and integration tests pass.
  • Skill manifest compatibility and MCP skill tests pass.
  • Agent runtime unit and golden tests pass.
  • CLI tests pass.
  • Full workspace tests pass, or documented exclusions are approved.

4. Feature Matrix (CI Covered)

The CI feature matrix intentionally checks selected combinations instead of --all-features, because some optional integrations are designed for external services or heavier local runtimes.

Current feature inventory:

  • yanshi-core: observability.
  • yanshi-mcp: client, server, stdio, http.
  • yanshi-cli: mcp, rag.
  • yanshi-llm: openai, anthropic, google, observability, logging.
  • yanshi-nodes: llm, http, file, template, batch, conditional, factories, mcp, rag.
  • yanshi-rag: qdrant, local-embeddings, pdf, html.
  • yanshi-tracing: postgres.
  • yanshi-agents: empty default feature set.

CI-covered combinations:

cargo check -p yanshi-core --features observability --target-dir /tmp/yanshi-target
cargo check -p yanshi-mcp --features client,server,stdio --target-dir /tmp/yanshi-target
cargo check -p yanshi-cli --no-default-features --features mcp --target-dir /tmp/yanshi-target
cargo check -p yanshi-cli --no-default-features --features rag --target-dir /tmp/yanshi-target
  • CI-covered feature combinations pass.
  • Any skipped feature combination is documented with service/runtime requirements.

5. Integration Smoke Tests (CI Covered)

HOME=/tmp/yanshi-home CARGO_HOME=$HOME/.cargo RUSTUP_HOME=$HOME/.rustup \
  cargo test --workspace --examples --target-dir /tmp/yanshi-target
HOME=/tmp/yanshi-home CARGO_HOME=$HOME/.cargo RUSTUP_HOME=$HOME/.rustup \
  cargo run -p yanshi-core --example fixed_dag_workflow --target-dir /tmp/yanshi-target
HOME=/tmp/yanshi-home CARGO_HOME=$HOME/.cargo RUSTUP_HOME=$HOME/.rustup \
  cargo run -p yanshi-agents --example agent_native_react --target-dir /tmp/yanshi-target
HOME=/tmp/yanshi-home CARGO_HOME=$HOME/.cargo RUSTUP_HOME=$HOME/.rustup \
  cargo run -p yanshi-agents --example plan_execute_agent --target-dir /tmp/yanshi-target
HOME=/tmp/yanshi-home CARGO_HOME=$HOME/.cargo RUSTUP_HOME=$HOME/.rustup \
  cargo run -p yanshi-cli --target-dir /tmp/yanshi-target -- workflow run yanshi-cli/examples/workflows/fixed_dag_basic.yml --dry-run
HOME=/tmp/yanshi-home CARGO_HOME=$HOME/.cargo RUSTUP_HOME=$HOME/.rustup \
  cargo run -p yanshi-cli --target-dir /tmp/yanshi-target -- workflow run yanshi-cli/examples/workflows/skill_agent_hybrid.yml --dry-run
HOME=/tmp/yanshi-home CARGO_HOME=$HOME/.cargo RUSTUP_HOME=$HOME/.rustup \
  cargo run -p yanshi-cli --features rag --target-dir /tmp/yanshi-target -- workflow run yanshi-cli/examples/workflows/rag_skill_assistant.yml --dry-run
HOME=/tmp/yanshi-home CARGO_HOME=$HOME/.cargo RUSTUP_HOME=$HOME/.rustup \
  cargo run -p yanshi-cli --target-dir /tmp/yanshi-target -- skill index validate yanshi-skills/examples/skills.index.toml
HOME=/tmp/yanshi-home CARGO_HOME=$HOME/.cargo RUSTUP_HOME=$HOME/.rustup \
  cargo run -p yanshi-cli --target-dir /tmp/yanshi-target -- skill index list yanshi-skills/examples/skills.index.toml
HOME=/tmp/yanshi-home CARGO_HOME=$HOME/.cargo RUSTUP_HOME=$HOME/.rustup \
  cargo run -p yanshi-cli --target-dir /tmp/yanshi-target -- skill index resolve yanshi-skills/examples/skills.index.toml mcp-demo
HOME=/tmp/yanshi-home CARGO_HOME=$HOME/.cargo RUSTUP_HOME=$HOME/.rustup \
  cargo run -p yanshi-cli --target-dir /tmp/yanshi-target -- skill validate yanshi-skills/examples/skills/mcp-basic
HOME=/tmp/yanshi-home CARGO_HOME=$HOME/.cargo RUSTUP_HOME=$HOME/.rustup \
  cargo run -p yanshi-cli --target-dir /tmp/yanshi-target -- skill list-tools yanshi-skills/examples/skills/mcp-basic
HOME=/tmp/yanshi-home CARGO_HOME=$HOME/.cargo RUSTUP_HOME=$HOME/.rustup \
  cargo run -p yanshi-skills --example skill_calls_mcp_tool --target-dir /tmp/yanshi-target
HOME=/tmp/yanshi-home CARGO_HOME=$HOME/.cargo RUSTUP_HOME=$HOME/.rustup \
  cargo run -p yanshi-agents --example hybrid_workflow_agent --target-dir /tmp/yanshi-target
  • Workspace examples compile.
  • Fixed DAG example runs.
  • Agent-native ReAct mock example runs.
  • Plan-and-Execute mock example runs.
  • Config-first fixed DAG, Skill-agent, and RAG + Skill dry-runs pass.
  • Skill registry index validates, lists, and resolves.
  • DAG + Agent hybrid example runs.
  • Skill examples validate and list tools through the CLI.
  • A local MCP skill can validate, list tools, and run a tool call.

6. Runtime Contracts (Manual)

  • AgentRunResult golden fixture changes are intentional and reviewed.
  • Workflow checkpoint resume still skips completed nodes.
  • AgentNode output includes response, session_id, stop_reason, and agent_result.
  • WorkflowTool exposes schema and timeout behavior as documented.
  • Trace output links workflow, agent, tool, and MCP calls where applicable.

7. Documentation (Manual)

  • README.md reflects the current release positioning.
  • docs/AGENT_RUNTIME.md matches runtime behavior.
  • docs/SKILL_FORMAT.md matches SKILL.md / skill.toml behavior.
  • MCP skill docs cover server naming, tool naming, and error behavior.
  • Release notes include breaking changes, migration notes, and known issues.
  • Examples referenced by docs compile or run.

8. Version And Packaging (Manual)

  • Crate versions are updated consistently.
  • Cargo.lock is intentionally updated.
  • Feature flags and default features are reviewed.
  • cargo package --list for publishable crates excludes local artifacts.
  • Release notes and tag name match the version.

9. Final Gate (Manual)

git diff --check
git status --short --ignored
  • No whitespace errors.
  • No unintended tracked changes.
  • release gate passed on the release branch or tag.
  • Release commit is tagged only after all required checks pass.
  • Any skipped check is recorded in the release notes with owner and reason.

10. Release Artifacts (Automated — P10.0.4)

Triggered automatically when a v*.*.* tag is pushed to GitHub. The .github/workflows/release.yml workflow runs three jobs in parallel-then-aggregate:

  1. build-binaries — matrix of 4 targets (linux x86_64, linux aarch64, macOS Intel, macOS Apple Silicon). Produces yanshi-<target>.tar.gz containing the yanshi CLI binary at archive root, plus a .sha256 per archive.
  2. build-docker — multi-arch (linux/amd64 + linux/arm64) yanshi-server image built via docker buildx with QEMU, pushed to ghcr.io/<owner>/yanshi-server:<tag> (+ :latest when the tag has no pre-release suffix).
  3. publish-release — aggregates the tarballs + a combined SHA256SUMS.txt, creates the GitHub Release on the same tag, marks pre-releases automatically when the tag carries a - suffix.

Manual dispatch (rehearsal mode)

The workflow also accepts workflow_dispatch with two inputs:

  • ref — tag or branch to build (default: current ref).
  • dry_run — when true (default), skips the GHCR push and the release publish; binaries still build + upload as Actions artifacts, the docker image still buildx-runs through the multi-arch pipeline but never pushes. Useful for verifying the matrix on a branch before the actual tag cut.

First-push prerequisites

  • GHCR package yanshi-server is set to public visibility after the first successful push (default for newly-created GHCR packages is private). Repository admin only; visible from GitHub package settings.
  • The GITHUB_TOKEN scope on the workflow is sufficient — the workflow declares packages: write at the docker job and contents: write at the publish job; these are honored by secrets.GITHUB_TOKEN automatically.
  • The ubuntu-24.04-arm runner is available to the repo (GA since 2025 — should be automatic for public repos and most paid plans).

Local rehearsal

scripts/release_dry_run/run.sh walks the same build steps locally (release-mode CLI binary build + docker buildx of the Dockerfile without pushing). Catches Dockerfile or feature-flag breakage before the tag cut.