github-release-best-practices

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

GitHub Release Best Practices

GitHub发布最佳实践

Systematic approach to GitHub release preparation following 2025 best practices for Rust workspace projects.

本文介绍遵循2025年最佳实践的Rust工作区项目GitHub发布准备系统化方法。

Purpose

目标

Establish comprehensive release management procedures for Rust workspaces with multiple crates, ensuring professional-grade releases with proper versioning, changelog management, and quality gate enforcement.

为包含多个crate的Rust工作区建立全面的发布管理流程，确保发布具备专业级别的版本控制、变更日志管理和质量门控机制。

2025 GitHub Release Best Practices

2025年GitHub发布最佳实践

Immutable Releases (New in 2025)

不可变发布（2025年新增）

What it is: GitHub's supply chain security feature that locks releases after publication.

Key Benefits:

Assets cannot be added, modified, or deleted after publishing
Release tags are protected and cannot be moved
Cryptographic attestations enable verification
Protects against post-release tampering

Implementation Strategy:

bash

undefined

定义：GitHub的供应链安全功能，发布后会锁定版本内容。

核心优势:

发布后无法添加、修改或删除资产
发布标签受保护，无法被移动
加密认证支持验证功能
防止发布后的篡改行为

实施策略:

bash

undefined

Draft-first approach for immutable releases

不可变发布的草稿优先方法

gh release create v0.1.8 --draft

Review content, attach assets, then publish

审核内容、附加资产后再发布

gh release edit v0.1.8 --publish

undefined

gh release edit v0.1.8 --publish

undefined

Auto-Generated Release Notes

自动生成发布说明

Features:

Lists merged pull requests automatically
Identifies and lists contributors
Provides links to full changelog
Customizable via
```
.github/release.yml
```
configuration

Configuration Example (

.github/release.yml

yaml

changelog:
  exclude:
    labels:
      - ignore-for-release
      - dependencies
    authors:
      - dependabot
  categories:
    - title: 🚀 New Features
      labels:
        - feature
        - enhancement
    - title: 🐛 Bug Fixes
      labels:
        - bug
        - fix
    - title: 📚 Documentation
      labels:
        - documentation
        - docs
    - title: 🔧 Other Changes
      labels:
        - "*"

Best Practice: Use auto-generation as starting point, then always review and refine before publishing. Recent implementations show 90% reduction in effort (2-3 hours → 15 minutes review time).

功能特性:

自动列出已合并的Pull Request
识别并列出贡献者
提供完整变更日志的链接
可通过
```
.github/release.yml
```
配置自定义内容

配置示例（

.github/release.yml

）:

yaml

changelog:
  exclude:
    labels:
      - ignore-for-release
      - dependencies
    authors:
      - dependabot
  categories:
    - title: 🚀 New Features
      labels:
        - feature
        - enhancement
    - title: 🐛 Bug Fixes
      labels:
        - bug
        - fix
    - title: 📚 Documentation
      labels:
        - documentation
        - docs
    - title: 🔧 Other Changes
      labels:
        - "*"

最佳实践：以自动生成的内容为基础，发布前务必审核并优化。近期实践显示，这种方式可将工作量减少90%（从2-3小时缩短至15分钟审核时间）。

Automated Changelog Generation from Git History

基于Git历史自动生成变更日志

Git Command Strategies

Git命令策略

Analyze Changes Since Last Release:

bash

undefined

分析上次发布后的变更:

bash

undefined

Get commits since last release

获取上次发布后的提交记录

git log v0.1.7..HEAD --oneline --decorate

Group commits by type using conventional commits

使用约定式提交按类型分组提交

git log --grep="^feat|^fix|^docs|^chore|^refactor" v0.1.7..HEAD

Generate commit summary with PR references

生成包含PR引用的提交摘要

git log v0.1.7..HEAD --pretty=format:"- %s (%h)" --abbrev-commit


**Extract PR Information**:
```bash

git log v0.1.7..HEAD --pretty=format:"- %s (%h)" --abbrev-commit


**提取PR信息**:
```bash

Get PR numbers from commit messages

从提交消息中获取PR编号

git log v0.1.7..HEAD --grep="#[0-9]" --pretty=format:"- %s (Closes %h)"

Extract breaking changes

提取破坏性变更

git log v0.1.7..BREAKING --pretty=format:"- BREAKING: %s"

undefined

git log v0.1.7..BREAKING --pretty=format:"- BREAKING: %s"

undefined

Keep a Changelog Format Implementation

基于Keep a Changelog格式的实现

Required Structure:

markdown

undefined

必填结构:

markdown

undefined

Changelog

All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

[Unreleased]

Added

Feature X for use case Y

Feature X for use case Y

Changed

Improved performance of Z

Improved performance of Z

[0.1.8] - 2025-12-28

Fixed

Resolved clippy warning in premem_integration_test.rs
Fixed unnecessary_unwrap pattern in test code

Resolved clippy warning in premem_integration_test.rs
Fixed unnecessary_unwrap pattern in test code

Changed

Improved error messages in integration tests
Inlined format arguments in semantic_summary_test.rs

Improved error messages in integration tests
Inlined format arguments in semantic_summary_test.rs

Added

GOAP execution plan documentation


**Categories (in order)**:
1. **Added** - New features
2. **Changed** - Changes to existing functionality  
3. **Deprecated** - Features planned for removal
4. **Removed** - Removed features
5. **Fixed** - Bug fixes
6. **Security** - Security vulnerability patches

GOAP execution plan documentation


**分类顺序**:
1. **Added** - 新增功能
2. **Changed** - 现有功能变更  
3. **Deprecated** - 计划移除的功能
4. **Removed** - 已移除的功能
5. **Fixed** - Bug修复
6. **Security** - 安全漏洞补丁

Version Bump Strategies for Rust Workspaces

Rust工作区的版本升级策略

Semantic Versioning Decision Matrix

语义化版本（Semantic Versioning）决策矩阵

Change Type	Version Bump	Example	Rationale
Breaking Changes	MAJOR	0.1.7 → 1.0.0	Public API changes
New Features	MINOR	0.1.7 → 0.2.0	Backward-compatible additions
Bug Fixes	PATCH	0.1.7 → 0.1.8	Backward-compatible fixes
CI/Quality	PATCH	0.1.7 → 0.1.8	Infrastructure improvements
Documentation	PATCH	0.1.7 → 0.1.8	Non-functional changes

变更类型	版本升级类型	示例	理由
破坏性变更	MAJOR	0.1.7 → 1.0.0	公共API变更
新增功能	MINOR	0.1.7 → 0.2.0	向后兼容的功能新增
Bug修复	PATCH	0.1.7 → 0.1.8	向后兼容的问题修复
CI/质量优化	PATCH	0.1.7 → 0.1.8	基础设施改进
文档更新	PATCH	0.1.7 → 0.1.8	非功能性变更

Workspace Version Coordination

工作区版本协调

Root Cargo.toml Management:

toml

[workspace.package]
version = "0.1.8"  # Single source of truth

[workspace.members]

根目录Cargo.toml管理:

toml

[workspace.package]
version = "0.1.8"  # 版本唯一可信源

[workspace.members]

All members inherit workspace.package version

所有成员继承workspace.package中的版本


**Version Validation**:
```bash


**版本验证**:
```bash

Check version consistency across workspace

检查工作区中的版本一致性

cargo metadata --format-version 1 --no-deps |
jq '.packages[] | select(.name != "rust-self-learning-memory") | {name, version}'

Validate all crates have consistent versions

验证所有crate版本一致

cargo workspaces version --all

undefined

cargo workspaces version --all

undefined

Special Considerations for 0.x Versions

0.x版本的特殊注意事项

During 0.x Development:

"Anything MAY change at any time"
"The public API SHOULD NOT be considered stable"
Standard semver guarantees are relaxed
Typically increment MINOR (0.1.x → 0.2.0) for most changes
PATCH reserved for critical bug fixes only

0.x开发阶段:

"任何内容都可能随时变更"
"公共API不应被视为稳定"
标准SemVer保证不适用
大多数变更通常递增MINOR版本（0.1.x → 0.2.0）
PATCH版本仅用于关键Bug修复

Release Validation Workflows

发布验证工作流

Pre-Release Quality Gates

发布前质量门控

CI/CD Validation:

bash

undefined

CI/CD验证:

bash

undefined

Run comprehensive quality checks

运行全面质量检查

./scripts/quality-gates.sh

Specific validations

专项验证

./scripts/code-quality.sh fmt ./scripts/code-quality.sh clippy --workspace cargo test --all cargo audit cargo deny check


**Coverage Requirements**:
- Maintain >90% test coverage across all modules
- Zero clippy warnings with strict linting
- All GitHub Actions workflows passing
- Security audit clean with no known vulnerabilities

./scripts/code-quality.sh fmt ./scripts/code-quality.sh clippy --workspace cargo test --all cargo audit cargo deny check


**覆盖率要求**:
- 所有模块测试覆盖率维持在90%以上
- 开启严格检查后零Clippy警告
- 所有GitHub Actions工作流执行通过
- 安全审计无已知漏洞

Release Creation Validation

发布创建验证

Git Tag Management:

bash

undefined

Git标签管理:

bash

undefined

Create annotated tag with release message

创建带发布说明的附注标签

git tag -a v0.1.8 -m "Release v0.1.8 - CI fixes and code quality improvements"

Verify tag creation

验证标签创建

git show v0.1.8

Push tag to trigger release workflow

推送标签触发发布工作流

git push origin v0.1.8


**GitHub Release Validation**:
```bash

git push origin v0.1.8


**GitHub发布验证**:
```bash

Create release with auto-generated notes

使用自动生成的说明创建发布

gh release create v0.1.8
--title "v0.1.8 - CI Fixes and Code Quality"
--notes "See CHANGELOG.md for details"

Verify release creation

验证发布创建

gh release view v0.1.8 --json tagName,createdAt,url

undefined

gh release view v0.1.8 --json tagName,createdAt,url

undefined

Release Note Templates and Examples

发布说明模板与示例

Patch Release Template (v0.X.Y)

补丁版本发布模板（v0.X.Y）

markdown

undefined

markdown

undefined

Summary

摘要

This patch release resolves critical bugs, improves code quality, and enhances CI/CD reliability. All changes are backward-compatible.

本次补丁版本修复了关键Bug，提升了代码质量，并增强了CI/CD可靠性。所有变更均向后兼容。

Fixed

修复内容

Clippy Warnings: Resolved
```
unnecessary_unwrap
```
lint in premem_integration_test.rs by refactoring to use proper match patterns
Performance Tests: Fixed type conversion compilation error in performance.rs
Release Workflow: Corrected asset upload failure by updating action version

Clippy警告: 通过重构为正确的match模式，修复了premem_integration_test.rs中的
```
unnecessary_unwrap
```
lint警告
性能测试: 修复了performance.rs中的类型转换编译错误
发布工作流: 通过更新Action版本修正了资产上传失败问题

Changed

变更内容

Improved error messages in integration tests (replaced
```
.unwrap()
```
with
```
.expect()
```
)
Inlined format arguments in semantic_summary tests for improved readability
Enforced warnings-as-errors consistently across all CI workflows

改进了集成测试中的错误信息（将
```
.unwrap()
```
替换为
```
.expect()
```
）
内联了semantic_summary测试中的格式参数，提升可读性
在所有CI工作流中统一启用了警告视为错误的规则

Added

新增内容

GOAP execution plan documentation for complex workflows
Response validation test suite for memory-mcp server

为复杂工作流添加了GOAP执行计划文档
为memory-mcp服务器添加了响应验证测试套件

Technical Details

技术细节

All GitHub Actions workflows passing (Quick Check, Performance Benchmarks, Security, CodeQL)
Zero clippy warnings with -D warnings enforcement
Test coverage maintained at 92.5%
Performance targets exceeded across all metrics

所有GitHub Actions工作流执行通过（快速检查、性能基准测试、安全检查、CodeQL）
开启-D warnings规则后零Clippy警告
测试覆盖率维持在92.5%
所有性能指标均超出目标

Full Changelog

完整变更日志

https://github.com/d-o-hub/rust-self-learning-memory/compare/v0.1.7...v0.1.8

undefined

https://github.com/d-o-hub/rust-self-learning-memory/compare/v0.1.7...v0.1.8

undefined

Minor Release Template (v0.X.0)

次版本发布模板（v0.X.0）

markdown

undefined

markdown

undefined

Summary

摘要

This minor release introduces new features and enhancements while maintaining backward compatibility. Key highlights include multi-provider embeddings, improved security, and performance optimizations.

本次次版本发布引入了新功能与增强特性，同时保持向后兼容。核心亮点包括多提供商嵌入、安全性提升和性能优化。

Added

新增内容

Multi-Provider Embeddings: Support for OpenAI, Cohere, Ollama, and local CPU embeddings
Configuration Caching: Reduced API calls through intelligent caching
Wasmtime Sandbox: 6-layer defense-in-depth security architecture
Vector Search Optimization: Improved similarity search performance

多提供商嵌入: 支持OpenAI、Cohere、Ollama和本地CPU嵌入
配置缓存: 通过智能缓存减少API调用
Wasmtime沙箱: 6层纵深防御安全架构
向量搜索优化: 提升了相似性搜索性能

Changed

变更内容

[BREAKING] Migrated from bincode to postcard for serialization
Performance improvements: 10-100x faster than baselines
Enhanced security with zero clippy warnings across all crates
Improved cache hit rates with new configuration caching

[破坏性变更] 从bincode迁移至postcard进行序列化
性能提升：比基准快10-100倍
所有crate零Clippy警告，安全性增强
新的配置缓存提升了缓存命中率

Breaking Changes

破坏性变更

Serialization Format: Existing redb databases must be recreated
- Postcard format is incompatible with previous bincode format
- See migration guide for step-by-step instructions
- Postcard provides better security guarantees

序列化格式: 现有redb数据库需重新创建
- Postcard格式与旧版bincode格式不兼容
- 请参考迁移指南获取分步说明
- Postcard提供更强的安全保障

Performance

性能数据

Episode Creation: 19,531x faster (~2.5 µs vs 50ms target)
Step Logging: 17,699x faster (~1.1 µs vs 20ms target)
Memory Retrieval: 138x faster (~721 µs vs 100ms target)

Episode创建：快19531倍（约2.5微秒 vs 目标50毫秒）
步骤日志：快17699倍（约1.1微秒 vs 目标20毫秒）
内存检索：快138倍（约721微秒 vs 目标100毫秒）

Security

安全性

Postcard Serialization: Safer than bincode, preventing deserialization attacks
Wasmtime Sandbox: 6-layer defense-in-depth security
Zero Clippy Warnings: Enforced strict linting across all code

Postcard序列化: 比bincode更安全，可防止反序列化攻击
Wasmtime沙箱: 6层纵深防御安全架构
零Clippy警告: 所有代码均启用严格检查

Migration Guide

迁移指南

Backup existing data: Export redb databases before upgrading
Update dependencies: Update to latest versions of dependencies
Recreate databases: Postcard format requires fresh database creation
Verify functionality: Run test suite to ensure compatibility

备份现有数据: 升级前导出redb数据库
更新依赖: 更新至最新版本的依赖包
重新创建数据库: Postcard格式需要全新数据库
验证功能: 运行测试套件确保兼容性

Statistics

统计数据

Test Pass Rate: 99.3% (424/427 tests passing)
Test Coverage: 92.5% across all modules
Rust Source Files: 367 files with ~44,250 LOC
Workspace Members: 8 crates

测试通过率：99.3%（427项测试中424项通过）
测试覆盖率：所有模块平均92.5%
Rust源文件：367个文件，约44250行代码
工作区成员：8个crate

Full Changelog

完整变更日志

https://github.com/d-o-hub/rust-self-learning-memory/compare/v0.1.7...v0.2.0

undefined

https://github.com/d-o-hub/rust-self-learning-memory/compare/v0.1.7...v0.2.0

undefined

Release Workflow Automation

发布工作流自动化

Complete Release Script

完整发布脚本

bash

#!/bin/bash

bash

#!/bin/bash

release-workflow.sh - Complete release automation

release-workflow.sh - 完整发布自动化脚本

set -e

RELEASE_VERSION=$1 if [ -z "$RELEASE_VERSION" ]; then echo "Usage: $0 <version>" echo "Example: $0 0.1.8" exit 1 fi

echo "🚀 Starting release workflow for v$RELEASE_VERSION"

set -e

RELEASE_VERSION=$1 if [ -z "$RELEASE_VERSION" ]; then echo "Usage: $0 <version>" echo "Example: $0 0.1.8" exit 1 fi

echo "🚀 Starting release workflow for v$RELEASE_VERSION"

1. Quality Gates

1.质量门控

echo "📋 Running quality gates..." ./scripts/quality-gates.sh

2. Update changelog

2.更新变更日志

echo "📝 Updating CHANGELOG.md..."

Implementation depends on changelog tool selection

实现方式取决于所选的变更日志工具

3. Commit changelog

3.提交变更日志

echo "💾 Committing changelog..." git add CHANGELOG.md git commit -m "docs(changelog): update for v$RELEASE_VERSION"

4. Create and push tag

4.创建并推送标签

echo "🏷️ Creating git tag v$RELEASE_VERSION..." git tag -a "v$RELEASE_VERSION" -m "Release v$RELEASE_VERSION" git push origin "v$RELEASE_VERSION"

5. Create GitHub release

5.创建GitHub发布

echo "🎉 Creating GitHub release..." gh release create "v$RELEASE_VERSION"
--title "v$RELEASE_VERSION - [Auto-generated]"
--notes "See CHANGELOG.md for detailed changes"
--draft

echo "✅ Release workflow completed!" echo "Next: Review release draft at https://github.com/d-o-hub/rust-self-learning-memory/releases"

undefined

echo "🎉 Creating GitHub release..." gh release create "v$RELEASE_VERSION"
--title "v$RELEASE_VERSION - [Auto-generated]"
--notes "See CHANGELOG.md for detailed changes"
--draft

echo "✅ Release workflow completed!" echo "Next: Review release draft at https://github.com/d-o-hub/rust-self-learning-memory/releases"

undefined

CI/CD Integration

CI/CD集成

Release Workflow Configuration (

.github/workflows/release.yml

yaml

name: Release
on:
  push:
    tags:
      - 'v*'

jobs:
  release:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: Setup Rust
        uses: dtolnay/rust-toolchain@stable
        with:
          components: cargo, clippy, rustfmt
       
      - name: Run quality gates
        run: ./scripts/quality-gates.sh
       
      - name: Create release
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          VERSION=${GITHUB_REF#refs/tags/}
          gh release create "$VERSION" \
            --title "Release $VERSION" \
            --notes-file CHANGELOG.md \
            --draft

发布工作流配置（

.github/workflows/release.yml

）:

yaml

name: Release
on:
  push:
    tags:
      - 'v*'

jobs:
  release:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: Setup Rust
        uses: dtolnay/rust-toolchain@stable
        with:
          components: cargo, clippy, rustfmt
       
      - name: Run quality gates
        run: ./scripts/quality-gates.sh
       
      - name: Create release
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          VERSION=${GITHUB_REF#refs/tags/}
          gh release create "$VERSION" \
            --title "Release $VERSION" \
            --notes-file CHANGELOG.md \
            --draft

Modern Release Tooling (2026 — ADR-034)

现代发布工具（2026年 — ADR-034）

cargo-semver-checks (API Compatibility)

cargo-semver-checks（API兼容性检查）

bash

cargo install --locked cargo-semver-checks
cargo semver-checks check-release --workspace

Catches accidental breaking changes before release.

bash

cargo install --locked cargo-semver-checks
cargo semver-checks check-release --workspace

可在发布前捕获意外的破坏性变更。

cargo-release (Version Management)

cargo-release（版本管理）

bash

cargo install --locked cargo-release

bash

cargo install --locked cargo-release

Handles version bump, commit, tag, push in one command

一键处理版本升级、提交、标签、推送

cargo release patch # or minor/major


Configure via `release.toml`:
```toml
[workspace]
allow-branch = ["main"]
pre-release-commit-message = "release: v{{version}}"
tag-message = "v{{version}}"
tag-prefix = "v"

cargo release patch # 或minor/major


通过`release.toml`配置:
```toml
[workspace]
allow-branch = ["main"]
pre-release-commit-message = "release: v{{version}}"
tag-message = "v{{version}}"
tag-prefix = "v"

cargo-dist (Binary Distribution)

cargo-dist（二进制分发）

bash

cargo install --locked cargo-dist
cargo dist init

Generates: platform tarballs, checksums (SHA256), shell/PowerShell installers, release.yml workflow.

CRITICAL: Version Must Match Tag cargo-dist requires

Cargo.toml

version to match the git tag. If they mismatch:

× This workspace doesn't have anything for dist to Release!
help: --tag=v0.1.21 will Announce: memory-mcp, memory-cli

Prevention:

Use
```
cargo release
```
(handles version + tag atomically)
Or manually verify:
```
grep '^version =' Cargo.toml
```
matches tag (without 'v')

v0.1.22 Incident: Tag pushed with Cargo.toml still at 0.1.21 → workflow failed.

bash

cargo install --locked cargo-dist
cargo dist init

生成：平台压缩包、SHA256校验和、Shell/PowerShell安装程序、release.yml工作流。

关键注意事项：版本必须与标签匹配 cargo-dist要求

Cargo.toml

中的版本与Git标签一致。若不匹配会出现以下错误：

× This workspace doesn't have anything for dist to Release!
help: --tag=v0.1.21 will Announce: memory-mcp, memory-cli

预防措施:

使用
```
cargo release
```
（自动原子化处理版本与标签）
或手动验证：
```
grep '^version =' Cargo.toml
```
的结果与标签（去除'v'前缀）一致

v0.1.22事件: 推送标签时Cargo.toml版本仍为0.1.21 → 工作流执行失败。

References

参考资料

ADR-034: Release Engineering Modernization
ADR-031: Cargo Lock Integrity

ADR-034: 发布工程现代化
ADR-031: Cargo Lock完整性

Integration with Agents

与Agent的集成

This skill provides foundational knowledge for:

release-guard: Gatekeeper for safe releases
goap-agent: Handles complex multi-phase release coordination
code-quality: Pre-release quality validation
github-workflows: CI/CD pipeline management

本技能为以下Agent提供基础支持：

release-guard: 安全发布的守护进程
goap-agent: 处理复杂的多阶段发布协调
code-quality: 发布前质量验证
github-workflows: CI/CD流水线管理