Contributing

​

Getting Started

​

1. Fork and Clone

git clone https://github.com/YOUR-USERNAME/gitwhisper.git
cd gitwhisper

​

2. Create a Branch

• feat/brief-description for new features
• fix/brief-description for bug fixes
• docs/brief-description for documentation changes
• refactor/brief-description for code refactoring

git checkout -b feat/add-mistral-support

​

Development Setup

​

Prerequisites

• Dart SDK (^3.5.0)
• Git installed and configured

​

Installation

dart pub get

dart pub global activate --source=path .

​

Making Changes

​

1. Write Your Code

• Follow Dart’s official style guide
• This project uses very_good_analysis for linting
• Add comments for complex logic
• Keep functions focused and single-purpose

​

2. Run Tests

dart test

​

3. Run Analysis

dart analyze

​

4. Test Manually

# Test the CLI locally
dart run bin/gitwhisper.dart commit --model openai

# Test with different models
dart run bin/gitwhisper.dart commit --model claude

# Test other commands
dart run bin/gitwhisper.dart list-models
dart run bin/gitwhisper.dart analyze

​

5. Update Documentation

• Update the README.md
• Add/update code comments
• Update relevant documentation pages
• Add examples if applicable

​

Code Style

​

Dart Style Guide

• Use lowerCamelCase for variables and functions
• Use UpperCamelCase for classes and types
• Use lowercase_with_underscores for libraries and files
• Always use trailing commas for better diffs
• Prefer final over var where possible

​

Linting

dart analyze

​

Example Code Pattern

/// Generates a commit message using the specified AI model.
///
/// Returns the generated message or throws an [ApiException] if the API call fails.
Future<String> generateCommitMessage({
  required String diff,
  required String model,
  String? apiKey,
}) async {
  // Implementation here
}

​

Commit Messages

• feat: ✨ Add new feature
• fix: 🐛 Fix bug description
• docs: 📚 Update documentation
• test: 🧪 Add or update tests
• refactor: ♻️ Refactor code
• chore: 🔧 Update build or dependencies
• perf: ⚡ Performance improvements
• ci: 👷 CI/CD changes

gw commit

​

Pull Request Process

​

1. Open a PR

• Use a clear, descriptive title
• Follow the PR template if one exists
• Link related issues using keywords (Fixes #123, Closes #456)

​

2. Describe Your Changes

## What

Added support for Mistral AI models.

## Why

Mistral offers competitive pricing and performance for commit message generation.

## How

- Created `MistralGenerator` class
- Added Mistral variants to `model_variants.dart`
- Updated documentation
- Added tests for Mistral integration

## Testing

- Tested with `mistral-large-latest` model
- Verified API key handling
- Confirmed error handling works correctly

​

3. Reference Related Issues

• Fixes #123 - Closes the issue when PR is merged
• Relates to #456 - References without closing
• Part of #789 - Part of a larger issue

​

4. Ensure CI Passes

• ✅ Tests pass
• ✅ Analysis passes with no warnings
• ✅ Code coverage maintained
• ✅ Build succeeds

​

5. Respond to Feedback

• Respond to review comments promptly
• Make requested changes
• Explain your reasoning when necessary
• Be respectful and professional

​

Hacktoberfest

​

What to Contribute

​

🐛 Bug Fixes

​

✨ New Features

1. Open an issue describing your feature
2. Wait for feedback from maintainers
3. Start implementing once approved

​

📚 Documentation

• README.md
• Code comments
• Examples and tutorials
• API documentation

​

🧪 Tests

• Unit tests for new features
• Integration tests
• Edge case testing
• Performance testing

​

🌍 Translations

• Update the Language enum in lib/src/models/language.dart
• Add language name and country code
• Test with the new language

​

🤖 Model Support

1. Create a new generator class (e.g., YourModelGenerator)
2. Implement the CommitGenerator interface
3. Add model variants to model_variants.dart
4. Update the factory in commit_generator_factory.dart
5. Add tests
6. Update documentation

​

Areas That Need Help

• Additional test coverage
• Performance optimizations
• Better error handling and user feedback
• Support for more AI models and variants
• Integration with CI/CD platforms
• Plugin support for more editors

​

Guidelines

​

Keep Changes Focused

• ✅ One feature or fix per PR
• ✅ Related changes grouped together
• ❌ Mixing unrelated changes
• ❌ Massive PRs with dozens of files

​

One Feature Per PR

✅ Good: "feat: Add Mistral AI support"
❌ Bad: "feat: Add Mistral support and fix bug in Claude generator and update README"

​

Test Your Changes

• Run all tests
• Test manually with different scenarios
• Test edge cases
• Verify error handling

​

Be Respectful

• Be welcoming and inclusive
• Be respectful of differing viewpoints
• Accept constructive criticism gracefully
• Focus on what’s best for the community

​

Project Structure

gitwhisper/
├── bin/
│   └── main.dart              # Entry point
├── lib/
│   ├── src/
│   │   ├── commands/          # CLI commands
│   │   ├── models/            # AI model generators
│   │   ├── exceptions/        # Error handling
│   │   ├── git_utils.dart     # Git operations
│   │   ├── config_manager.dart # Configuration
│   │   └── ...
│   └── gitwhisper.dart        # Library exports
├── test/                      # Tests
├── pubspec.yaml               # Dependencies
└── README.md                  # Documentation

​

Development Workflow

1. Fork and clone the repository
2. Create a feature branch from master
3. Make your changes following our guidelines
4. Test thoroughly (automated and manual)
5. Commit using conventional commits (use GitWhisper!)
6. Push to your fork
7. Open a Pull Request with a clear description
8. Respond to reviews and make requested changes
9. Celebrate when your PR is merged! 🎉

​

Getting Help

• Open an issue for discussion
• Ask in your PR if you need guidance during development
• Check existing issues for similar questions
• Join discussions in GitHub Discussions

​

Resources

• Dart Language Tour
• Effective Dart
• Dart Package Layout
• Conventional Commits
• How to Write a Git Commit Message

​

Recognition

• Added to the contributors list
• Acknowledged in release notes
• Celebrated in the community