Contributing Guidelines

How to contribute to ReasonKit.

Code of Conduct

Be respectful, inclusive, and constructive. We’re building tools to help people think better—let’s model that in our interactions.

Ways to Contribute

Bug Reports

Found a bug? Open an issue with:

• ReasonKit version (rk version)
• OS and environment
• Steps to reproduce
• Expected vs actual behavior
• Relevant logs/output

Feature Requests

Have an idea? Start a discussion first to get feedback before implementing.

Documentation

• Fix typos and unclear explanations
• Add examples and use cases
• Improve API documentation
• Translate documentation

Code Contributions

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Submit a pull request

Pull Request Process

Before You Start

1. Check existing issues/PRs - Avoid duplicate work
2. Discuss major changes - Open an issue first
3. Understand the codebase - Read relevant code and docs

Branch Naming

feature/add-stakeholder-tool
fix/proofguard-timeout
docs/improve-api-examples
refactor/simplify-output-formatting

Commit Messages

Follow Conventional Commits:

feat(thinktools): add StakeholderMap tool
fix(proofguard): handle timeout gracefully
docs(api): add Python async examples
refactor(output): simplify format selection
test(gigathink): add edge case tests

PR Checklist

• Code compiles (cargo build)
• Tests pass (cargo test)
• Lints pass (cargo clippy -- -D warnings)
• Formatted (cargo fmt)
• Documentation updated
• CHANGELOG updated (for user-facing changes)

PR Description Template

## Summary

Brief description of changes.

## Motivation

Why is this change needed?

## Changes

- List of specific changes

## Testing

How was this tested?

## Screenshots

If applicable.

## Related Issues

Fixes #123

Code Style

Rust

Follow the Rust Style Guide:

#![allow(unused)]
fn main() {
// Good
pub fn analyze(&self, input: &str) -> Result<Analysis> {
    let processed = self.preprocess(input)?;
    let result = self.run_analysis(processed)?;
    Ok(result)
}

// Avoid
pub fn analyze(&self, input: &str) -> Result<Analysis>
{
    let processed = self.preprocess(input)?;
    let result = self.run_analysis(processed)?;
    return Ok(result);
}
}

Documentation

• Use doc comments (///) for public items
• Include examples in doc comments
• Keep comments concise and useful

#![allow(unused)]
fn main() {
/// Analyzes the input using the GigaThink methodology.
///
/// # Arguments
///
/// * `input` - The question or statement to analyze
///
/// # Returns
///
/// A `GigaThinkResult` containing perspectives and insights.
///
/// # Example
///
/// ```rust
/// let gt = GigaThink::new().perspectives(10);
/// let result = gt.analyze("Should I start a business?").await?;
/// ```
pub async fn analyze(&self, input: &str) -> Result<GigaThinkResult> {
    // ...
}
}

Error Handling

• Use Result types, not panics
• Provide context in errors
• Use thiserror for error types

#![allow(unused)]
fn main() {
use thiserror::Error;

#[derive(Error, Debug)]
pub enum AnalysisError {
    #[error("API request failed: {0}")]
    ApiError(#[from] reqwest::Error),

    #[error("Invalid configuration: {0}")]
    ConfigError(String),

    #[error("Analysis timed out after {0} seconds")]
    Timeout(u64),
}
}

Testing

• Write tests for new functionality
• Maintain test coverage
• Use meaningful test names

#![allow(unused)]
fn main() {
#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn gigathink_generates_minimum_perspectives() {
        let gt = GigaThink::new().perspectives(5);
        let result = gt.analyze("Test question").await.unwrap();
        assert!(result.perspectives.len() >= 5);
    }

    #[test]
    fn gigathink_handles_empty_input() {
        let gt = GigaThink::new();
        let result = gt.analyze("");
        assert!(result.is_err());
    }
}
}

Review Process

1. Automated checks - CI must pass
2. Code review - At least one maintainer approval
3. Discussion - Address feedback constructively
4. Merge - Maintainer merges after approval

Review Timeline

• Initial response: 2-3 business days
• Full review: 1-2 weeks for complex changes
• Simple fixes: May be merged same day

Recognition

Contributors are recognized in:

• CONTRIBUTORS.md
• Release notes
• Documentation credits

Getting Help

• GitHub Discussions: Questions and ideas
• Issues: Bug reports and feature requests

License

By contributing, you agree that your contributions will be licensed under the Apache 2.0 License.

Related

• Development Setup
• Architecture