0 Fork 0

Files

T

james.maes e8f656a13b docs: Add comprehensive documentation for release procedures and best practices

- docs/RELEASE-PROCEDURE.md - Complete release workflow guide
- docs/RUST-BEST-PRACTICES.md - Rust project best practices and guidelines
- docs/CLEAN-ROOM-AUDIT.md - Clean room audit results and resolution status

All recommended actions from the clean room audit are now complete:
- Tests moved to tests/ directory (39 tests)
- Windows target added to all platforms
- Release workflow verified for 5 platforms
- Homebrew formula published
- Branch protection enabled
- GitHub release v1.0.0 created with all assets

2026-06-02 14:31:50 -05:00

2.1 KiB

Raw Permalink Blame History

Release Procedure for notion-sql

Prerequisites

Before releasing, ensure:

All tests pass: cargo test --all-targets
Code is clean: cargo clippy --all-targets --all-features -- -D warnings
Formatting is correct: cargo fmt --check

Release Steps

1. Update Version

Bump version in Cargo.toml (e.g., version = "1.0.0")
Update CHANGELOG.md with release notes following Keep a Changelog format

2. Commit Changes

git add -A
git commit -m "chore: Update to v$VERSION"

3. Create Release Tag

git tag -a v$VERSION -m "notion-sql v$VERSION - [release notes]"
git push origin v$VERSION

4. Verify Release Workflow

Check GitHub Actions for the Release workflow run
Wait for all 5 platform binaries to build:
- macOS ARM64 (aarch64-apple-darwin)
- macOS x86_64 (x86_64-apple-darwin)
- Linux ARM64 (aarch64-unknown-linux-gnu)
- Linux x86_64 (x86_64-unknown-linux-gnu)
- Windows x86_64 (x86_64-pc-windows-msvc)

5. Publish Release

Once the workflow completes successfully:

gh release edit v$VERSION --draft=false

Platform Targets Configuration

The Cargo.toml [workspace.metadata.dist] section configures all targets:

targets = [
  "aarch64-apple-darwin",
  "aarch64-unknown-linux-gnu", 
  "x86_64-apple-darwin",
  "x86_64-unknown-linux-gnu",
  "x86_64-pc-windows-msvc"
]

Homebrew Integration

The release workflow automatically:

Builds Homebrew formula (notion-sql.rb)
Pushes to KofTwentyTwo/homebrew-tap repository
Users install via: brew install KofTwentyTwo/tap/notion-sql

Security

Release tags are protected via repository ruleset
Branch protection on main prevents force pushes and deletions
HOMEBREW_TAP_TOKEN secret is required for Homebrew formula publishing

Troubleshooting

Release Workflow Fails

Check GitHub Actions logs for the Release workflow
Common issues:
- Tag already exists (delete and recreate)
- Missing HOMEBREW_TAP_TOKEN secret
- Homebrew tap repository not accessible

Binaries Not Built

Verify targets in Cargo.toml includes all desired platforms
Check CI/CD workflow has permission to build all targets

2.1 KiB Raw Permalink Blame History