notion-sql/RELEASING.md

Releasing

Releases are built with dist and published by GitHub Actions.

Changelog Management

All releases must update the CHANGELOG.md file with:

1. Version number and release date
2. Category of changes (Added, Changed, Fixed)
3. Breaking changes if any

Follow the Keep a Changelog format.

Branch Flow

Use the repository's gitflow-style branches:

• feature/* branches hold active work and open PRs into develop.
• develop receives merged feature work and runs build/test CI plus branch artifact publishing.
• release/* or rc/* branches stabilize release candidates and run the same CI plus branch artifact publishing.
• main is production and should only receive release-ready changes.

Before pushing release tags, verify GitHub authentication:

gh auth status
git ls-remote --heads origin

Local Release Prep

1. Update version in Cargo.toml.

2. Update CHANGELOG.md with release notes.

3. Run:

   cargo fmt
   cargo clippy --all-targets --all-features -- -D warnings
   cargo test
   RUSTDOCFLAGS='-D warnings' cargo doc --no-deps --all-features
   cargo build --release
   cargo publish --dry-run --allow-dirty
   dist generate --check
   dist plan --tag vX.Y.Z
   

4. Commit the version bump.

Release Candidate

From a release candidate branch:

git tag vX.Y.Z-rc.N
git push origin vX.Y.Z-rc.N

The Release workflow builds all configured target binaries and creates a GitHub prerelease.

Production Release

From main:

1. Update CHANGELOG.md with release date.

2. Commit changelog changes:

   git commit -am "Update CHANGELOG for v$VERSION"
   

3. Tag and push:

   git tag vX.Y.Z
   git push origin vX.Y.Z
   

The Release workflow builds all configured target binaries, creates a GitHub Release, and publishes the Homebrew formula to:

KofTwentyTwo/homebrew-tap

End users install with:

brew install KofTwentyTwo/tap/notion-sql

Required GitHub Setup

Create or verify a public Homebrew tap repository:

KofTwentyTwo/homebrew-tap

Add a repository Actions secret on KofTwentyTwo/notion-sql named:

HOMEBREW_TAP_TOKEN

The token needs contents write access to KofTwentyTwo/homebrew-tap, because the release workflow checks out that repository and commits formula updates. Do not hardcode this token in workflow files.

Before the first production release:

• Protect or manage the main and develop branches according to the branch flow above.
• Confirm HOMEBREW_TAP_TOKEN can write to KofTwentyTwo/homebrew-tap.
• Confirm the local push path works with git ls-remote --heads origin.
• Re-run actionlint, dist generate --check, and dist plan --tag vX.Y.Z.

Notion API Compatibility

v0.1.0 intentionally ships against Notion-Version: 2022-06-28 and the legacy database endpoints. This version does not use the 2025-09-03 data source APIs.

The known limitation is that Notion workspaces using the newer multi-source database model can hit API validation or capability limits in v0.1.0. A future release should migrate database discovery and querying to data sources before changing the pinned Notion API version.