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 fmtcargo clippy- package test matrix for
yanshi-core,yanshi-tools,yanshi-memory,yanshi-mcp,yanshi-skills,yanshi-agents, andyanshi-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 --ignoredand 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)
-
AgentRunResultgolden fixture changes are intentional and reviewed. - Workflow checkpoint resume still skips completed nodes.
-
AgentNodeoutput includesresponse,session_id,stop_reason, andagent_result. -
WorkflowToolexposes schema and timeout behavior as documented. - Trace output links workflow, agent, tool, and MCP calls where applicable.
7. Documentation (Manual)
-
README.mdreflects the current release positioning. -
docs/AGENT_RUNTIME.mdmatches runtime behavior. -
docs/SKILL_FORMAT.mdmatchesSKILL.md/skill.tomlbehavior. - 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.lockis intentionally updated. - Feature flags and default features are reviewed.
-
cargo package --listfor 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 gatepassed 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:
build-binaries— matrix of 4 targets (linux x86_64, linux aarch64, macOS Intel, macOS Apple Silicon). Producesyanshi-<target>.tar.gzcontaining theyanshiCLI binary at archive root, plus a.sha256per archive.build-docker— multi-arch (linux/amd64 + linux/arm64)yanshi-serverimage built viadocker buildxwith QEMU, pushed toghcr.io/<owner>/yanshi-server:<tag>(+:latestwhen the tag has no pre-release suffix).publish-release— aggregates the tarballs + a combinedSHA256SUMS.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— whentrue(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-serveris set to public visibility after the first successful push (default for newly-created GHCR packages isprivate). Repository admin only; visible from GitHub package settings. - The
GITHUB_TOKENscope on the workflow is sufficient — the workflow declarespackages: writeat the docker job andcontents: writeat the publish job; these are honored bysecrets.GITHUB_TOKENautomatically. - The
ubuntu-24.04-armrunner 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.