Contributing to dartantic_ai

​

How to Contribute an Issue

​

How to Contribute a PR

​

1. Fork and Clone

1. Fork the repository on GitHub
2. Clone your fork locally:
   git clone https://github.com/csells/dartantic_ai.git
   cd dartantic_ai
   

​

2. Set Up Your Development Environment

​

Install Dependencies

dart pub get

​

Set Up API Keys for Testing

export OPENAI_API_KEY="your-openai-key"
export ANTHROPIC_API_KEY="your-anthropic-key"
export GEMINI_API_KEY="your-google-gemini-key"
export MISTRAL_API_KEY="your-mistral-key"
export COHERE_API_KEY="your-cohere-key"
export OPENROUTER_API_KEY="your-openrouter-key"
export TOGETHER_API_KEY="your-together-key"
export XAI_API_KEY="your-xai-key"

​

3. Run Tests

# Run all tests
dart test

# Run a specific test file
dart test test/specific_test_file.dart

# Run tests with timeout for long-running suites
dart test --timeout=10m

​

4. Make Your Changes

1. Create a new branch for your feature:
   git checkout -b feature/your-feature-name
   
2. Make your changes following the existing code style and patterns
3. Add tests for your new feature - This is critical!

​

5. Testing Your Changes

​

Test Requirements

• Every new feature must have tests
• Follow the testing philosophy in test files (no defensive programming)
• Test both success cases and edge cases
• Ensure your tests work across all applicable providers

​

Testing Best Practices

1. No Exception Hiding: Let exceptions bubble up for diagnosis
2. Provider Filtering: Only filter by test capabilities (e.g., ProviderTestCaps in run_provider_test.dart)
3. 80/20 Rule: Test common cases across all providers, edge cases on Google only
4. No Duplication: Each functionality should be tested in ONE file only

​

6. Verify Your Changes

1. Run all tests and ensure they pass:
   dart test
   
2. Format your code:
   dart format .
   
3. Analyze your code:
   dart analyze
   

​

7. Submit Your Pull Request

1. Commit your changes with a clear message:
   git commit -m "feat: add support for new feature X"
   
2. Push to your fork:
   git push origin feature/your-feature-name
   
3. Open a Pull Request on GitHub with:
   • Clear description of what you’ve added/changed
   • Reference to any related issues
   • Confirmation that all tests pass
   • Description of the tests you’ve added

​

Code Style Guidelines

• Follow Dart conventions and the existing code style
• Use meaningful variable and function names
• Add documentation comments for public APIs
• Keep functions focused and single-purpose

​

Need Help?

1. Check existing issues and discussions
2. Review the test files for examples
3. Open an issue for clarification