SDK Changelog Automation

ReasonKit uses an automated system to generate changelogs for our Rust, Python, and TypeScript SDKs. This ensures that every release is accompanied by clear, structured, and accurate release notes.

1. The Standard: Conventional Commits

Changelog automation relies on the Conventional Commits specification. All PRs must follow this format:

• feat:: A new feature (e.g., feat(core): add GigaThink module).
• fix:: A bug fix (e.g., fix(python): resolve memory leak in trace parser).
• perf:: Performance improvements.
• docs:: Documentation-only changes.
• breaking:: BREAKING CHANGE in the footer or ! after the type.

2. Automation Tooling

We use git-cliff to parse commits and generate the CHANGELOG.md file in each SDK directory.

Configuration

The configuration is stored in the project root: RK-PROJECT/cliff.toml.

GitHub Actions Workflow

The rk-changelog action runs on every push to main and on every new v* tag.

1. Parse: Scans commits since the last tag.
2. Generate: Uses cliff.toml to produce a Markdown string.
3. Commit: Updates the local CHANGELOG.md and commits it back to the branch (for releases).
4. Release: Includes the changelog snippet in the GitHub Release body.

3. Manual Generation

If you need to preview the changelog locally:

# Install git-cliff
cargo install git-cliff

# Generate for the upcoming release
git cliff --unreleased --config cliff.toml

4. Best Practices

• Scope Your Commits: Use brackets to indicate which SDK is affected: feat(sdk-js): add web-worker support.
• Body Descriptions: For complex features, include a body in your commit message. git-cliff is configured to include the body in the “Features” section.
• Breaking Changes: Always clearly mark breaking changes. These are highlighted at the top of the generated changelog to warn developers.