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:

Type	Pattern	Example
Feature	`feat/description`	`feat/add-streaming-output`
Bug fix	`fix/description`	`fix/timeout-handling`
Docs	`docs/description`	`docs/update-api-reference`
Refactor	`refactor/description`	`refactor/thinktool-registry`

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:

Type	When to Use
`feat`	New feature
`fix`	Bug fix
`docs`	Documentation only
`refactor`	Code change that neither fixes nor adds
`test`	Adding/updating tests
`perf`	Performance improvement
`chore`	Build, CI, dependencies

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

Automated Checks — CI runs tests, linting, formatting
Maintainer Review — Usually within 48 hours
Feedback — May request changes
Approval — At least one maintainer approval needed
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:

Check	Command	Requirement
Build	`cargo build --release`	Must compile
Tests	`cargo test`	All tests pass
Linting	`cargo clippy -- -D warnings`	No warnings
Format	`cargo fmt --check`	Properly formatted
Docs	`cargo doc --no-deps`	Docs compile

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