Pull Requests

🔀 How to submit code changes to ReasonKit.

We love contributions! This guide walks you through the PR process from start to merge.

Before You Start

1. Check Existing Issues

Before writing code, check if:

• There’s an existing issue for your change
• Someone else is already working on it
• The change aligns with project direction

# Search issues on GitHub
gh issue list --search "your feature"

2. Fork and Clone

# Fork on GitHub, then clone your fork
git clone https://github.com/YOUR-USERNAME/reasonkit-core.git
cd reasonkit-core

# Add upstream remote
git remote add upstream https://github.com/reasonkit/reasonkit-core.git

3. Create a Branch

# Always branch from main
git checkout main
git pull upstream main
git checkout -b your-branch-name

Branch naming:

Making Changes

1. Write Code

Follow the Code Style Guide:

# Format as you go
cargo fmt

# Check for issues
cargo clippy -- -D warnings

2. Write Tests

All changes need tests. See Testing Guide:

# Run tests frequently
cargo test

# Run specific test
cargo test test_name

3. Update Documentation

If your change affects:

• Public API → Update doc comments
• CLI behavior → Update docs/
• Configuration → Update docs/

4. Commit Changes

We follow Conventional Commits:

# Format: type(scope): description
git commit -m "feat(thinktool): add streaming support for GigaThink"
git commit -m "fix(cli): handle timeout correctly in quiet mode"
git commit -m "docs(api): document new output format options"

Commit types:

Submitting the PR

1. Push Your Branch

git push origin your-branch-name

2. Create the PR

# Using GitHub CLI
gh pr create --title "feat(thinktool): add streaming support" --body-file .github/PULL_REQUEST_TEMPLATE.md

# Or use GitHub web interface

3. PR Template

Every PR should include:

## Summary
Brief description of what this PR does.

## Changes
- [ ] Added streaming support to GigaThink
- [ ] Updated CLI to handle streaming output
- [ ] Added tests for streaming behavior

## Testing
How did you test this?
- `cargo test thinktool::streaming`
- Manual testing with `rk-core think "test" --stream`

## Screenshots (if applicable)
[Add terminal screenshots for UI changes]

## Checklist
- [ ] Code follows project style guidelines
- [ ] Tests pass locally (`cargo test`)
- [ ] Linting passes (`cargo clippy -- -D warnings`)
- [ ] Documentation updated (if needed)
- [ ] Commit messages follow conventional commits

Review Process

What to Expect

1. Automated Checks — CI runs tests, linting, formatting
2. Maintainer Review — Usually within 48 hours
3. Feedback — May request changes
4. Approval — At least one maintainer approval needed
5. Merge — Squash-merged to main

Responding to Feedback

# Make requested changes
git add .
git commit -m "refactor: address review feedback"
git push origin your-branch-name

For substantial changes, consider force-pushing a cleaner history:

# Rebase to clean up commits
git rebase -i HEAD~3  # Squash last 3 commits
git push --force-with-lease origin your-branch-name

CI Requirements

All PRs must pass:

After Merge

Your PR gets squash-merged to main. After merge:

# Update your local main
git checkout main
git pull upstream main

# Clean up your branch
git branch -d your-branch-name
git push origin --delete your-branch-name

PR Size Guidelines

Tip: Smaller PRs get reviewed faster and merged sooner.

Special Cases

Breaking Changes

PRs with breaking changes need:

• BREAKING CHANGE: in commit body
• Migration guide in PR description
• Explicit maintainer approval

Security Fixes

For security issues:

1. Don’t open a public PR
2. Email security@reasonkit.sh
3. We’ll coordinate a fix and disclosure

Dependencies

For dependency updates:

• Use cargo update for minor/patch updates
• Create separate PR for major version bumps
• Include changelog review in PR description

Getting Help

Stuck? Need guidance?

• Ask in the PR comments
• Join our Discord
• Check existing PRs for examples

Related

• Code Style — Coding standards
• Testing — Writing tests
• Architecture — System design