Github Release Best Practices

GitHub Release Best Practices

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

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.

2025 GitHub Release Best Practices

Immutable Releases (New in 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:

# 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

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):

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).

Automated Changelog Generation from Git History

Git Command Strategies

Analyze Changes Since Last Release:

# 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
git log v0.1.7..HEAD --pretty=format:"- %s (%h)" --abbrev-commit

Extract PR Information:

# Get PR numbers from commit messages
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"

Keep a Changelog Format Implementation

Required Structure:

# Changelog

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

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [Unreleased]

### Added
- Feature X for use case Y

### Changed
- 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

### Changed
- 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

Version Bump Strategies for Rust Workspaces

Semantic Versioning Decision Matrix

Workspace Version Coordination

Root Cargo.toml Management:

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

[workspace.members]
# All members inherit workspace.package version

Version Validation:

# 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
cargo workspaces version --all

Special Considerations for 0.x Versions

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

Release Validation Workflows

Pre-Release Quality Gates

CI/CD Validation:

# 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

Release Creation Validation

Git Tag Management:

# 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:

# 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

Release Note Templates and Examples

Patch Release Template (v0.X.Y)

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

## 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

## 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

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

## 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

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

Minor Release Template (v0.X.0)

## 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

## 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

## 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

## 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)

## 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

## Migration Guide
1. **Backup existing data**: Export redb databases before upgrading
2. **Update dependencies**: Update to latest versions of dependencies
3. **Recreate databases**: Postcard format requires fresh database creation
4. **Verify functionality**: Run test suite to ensure compatibility

## 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

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

Release Workflow Automation

Complete Release Script

#!/bin/bash
# release-workflow.sh - Complete release automation

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
echo "📋 Running quality gates..."
./scripts/quality-gates.sh

# 2. Update changelog
echo "📝 Updating CHANGELOG.md..."
# Implementation depends on changelog tool selection

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

# 4. Create and push tag
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
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"

CI/CD Integration

Release Workflow Configuration (.github/workflows/release.yml):

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)

cargo-semver-checks (API Compatibility)

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

Catches accidental breaking changes before release.

cargo-release (Version Management)

cargo install --locked cargo-release
# Handles version bump, commit, tag, push in one command
cargo release patch  # or minor/major

Configure via release.toml:

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

cargo-dist (Binary Distribution)

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: do-memory-mcp, do-memory-cli

Prevention:

1. Use cargo release (handles version + tag atomically)
2. 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.

References

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

Integration with Agents

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

Converted and distributed by TomeVault — claim your Tome and manage your conversions.