# Contributing to Flutter MCP 🎉

First off, **thank you** for considering contributing to Flutter MCP! 🙏 This is an open-source community project, and it's people like you who make it possible to give AI assistants real-time Flutter superpowers. Whether you're fixing a typo, reporting a bug, or adding a major feature, every contribution matters!

## 🌟 Ways to Contribute

There are many ways to contribute to Flutter MCP, and we value them all:

### 🐛 Report Bugs

Found something broken? [Open an issue](https://github.com/adamsmaka/flutter-mcp/issues/new?template=bug_report.md) and help us squash it!

### 💡 Suggest Features

Have an idea to make Flutter MCP even better? [Start a discussion](https://github.com/adamsmaka/flutter-mcp/discussions/new?category=ideas) or [open a feature request](https://github.com/adamsmaka/flutter-mcp/issues/new?template=feature_request.md)!

### 📖 Improve Documentation

Even the smallest documentation fix helps! Whether it's fixing a typo, clarifying instructions, or adding examples - documentation is crucial.

### 🧪 Write Tests

Help us maintain quality by adding tests. We aim for high test coverage to ensure Flutter MCP stays reliable.

### 🌐 Add Translations

Make Flutter MCP accessible to developers worldwide by helping with translations.

### ⭐ Spread the Word

Star the repo, share it with your Flutter community, write a blog post, or tweet about your experience!

### 💻 Write Code

Fix bugs, implement features, optimize performance - dive into the code and make Flutter MCP better!

## 🚀 Getting Started

### Prerequisites

Before you begin, ensure you have:

- Python 3.10 or higher
- Redis installed and running
- Git for version control
- A GitHub account

### Development Setup

1. **Fork the repository**

   Click the "Fork" button at the top right of the [Flutter MCP repository](https://github.com/adamsmaka/flutter-mcp).

2. **Clone your fork**

   ```bash
   git clone https://github.com/YOUR-USERNAME/flutter-mcp.git
   cd flutter-mcp
   ```

3. **Set up the development environment**

   ```bash
   # Create a virtual environment
   python -m venv venv

   # Activate it
   source venv/bin/activate  # On Windows: venv\Scripts\activate

   # Install dependencies in development mode
   pip install -e ".[dev]"
   ```

4. **Start Redis**

   ```bash
   # macOS
   brew services start redis

   # Linux
   sudo systemctl start redis

   # Docker
   docker run -d -p 6379:6379 --name flutter-mcp-redis redis:alpine
   ```

5. **Run the development server**

   ```bash
   # Run with MCP Inspector for debugging
   mcp dev src/flutter_mcp/server.py

   # Or run directly
   python -m flutter_mcp.server
   ```

For more detailed setup instructions, check out our [Development Guide](DEVELOPMENT.md).

## 📋 Before You Submit

### 🎨 Code Style Guidelines

We use Python's standard style guidelines with a few preferences:

- **Black** for code formatting (line length: 88)
- **isort** for import sorting
- **Type hints** for all public functions
- **Docstrings** for all classes and public methods

Run the formatters before committing:

```bash
# Format code
black src/ tests/

# Sort imports
isort src/ tests/

# Check types
mypy src/

# Run linter
ruff check src/ tests/
```

### 🧪 Testing Guidelines

All code changes should include tests:

```bash
# Run all tests
pytest

# Run with coverage
pytest --cov=flutter_mcp

# Run specific test file
pytest tests/test_server.py

# Run tests in watch mode
pytest-watch
```

We aim for at least 80% test coverage. Write tests that:

- Cover both happy paths and edge cases
- Are isolated and don't depend on external services
- Use mocks for Redis and external API calls
- Have descriptive names that explain what they test

### 📝 Commit Messages

We follow the [Conventional Commits](https://www.conventionalcommits.org/) specification:

```
feat: add support for package version constraints
fix: handle rate limiting from pub.dev API
docs: update Redis installation instructions
test: add tests for cache expiration
refactor: extract documentation parser into separate module
```

## 🔄 Pull Request Process

### 1. Create a Feature Branch

```bash
git checkout -b feature/your-feature-name
# or
git checkout -b fix/issue-description
```

### 2. Make Your Changes

- Write clean, readable code
- Add tests for new functionality
- Update documentation if needed
- Ensure all tests pass

### 3. Commit Your Changes

```bash
git add .
git commit -m "feat: add amazing new feature"
```

### 4. Push to Your Fork

```bash
git push origin feature/your-feature-name
```

### 5. Open a Pull Request

1. Go to the [Flutter MCP repository](https://github.com/adamsmaka/flutter-mcp)
2. Click "Compare & pull request"
3. Fill out the PR template:
   - Describe what changes you made
   - Link any related issues
   - Include screenshots if relevant
   - Check all the boxes in the checklist

### 6. Code Review

- Be patient and respectful during review
- Respond to feedback constructively
- Make requested changes promptly
- Ask questions if something isn't clear

## 🐛 Reporting Bugs

Found a bug? Help us fix it by providing detailed information:

1. **Search existing issues** first to avoid duplicates
2. **Use the bug report template** when creating an issue
3. **Include**:
   - Flutter MCP version (`flutter-mcp --version`)
   - Python version (`python --version`)
   - OS and version
   - Steps to reproduce
   - Expected behavior
   - Actual behavior
   - Error messages/logs
   - Screenshots if applicable

## 💡 Requesting Features

Have an idea? We'd love to hear it!

1. **Check existing issues and discussions** first
2. **Use the feature request template**
3. **Explain**:
   - The problem you're trying to solve
   - Your proposed solution
   - Alternative solutions you've considered
   - How it benefits other users

## 🤝 Community Guidelines

### Our Code of Conduct

We're committed to providing a welcoming and inclusive environment. By participating, you agree to:

- **Be respectful** - Treat everyone with respect
- **Be constructive** - Provide helpful feedback
- **Be inclusive** - Welcome newcomers and help them get started
- **Be patient** - Remember that everyone is volunteering their time
- **Be professional** - Keep discussions focused and productive

### Getting Help

- 💬 **Discord**: Join our [Flutter MCP Discord](https://discord.gg/flutter-mcp)
- 🤔 **Discussions**: Ask questions in [GitHub Discussions](https://github.com/adamsmaka/flutter-mcp/discussions)
- 📧 **Email**: Reach out to maintainers@flutter-mcp.dev

## 🏆 Recognition

We believe in recognizing our contributors!

### All Contributors

We use the [All Contributors](https://allcontributors.org/) specification to recognize everyone who helps make Flutter MCP better. Contributors are automatically added to our README.

### Types of Contributions We Recognize

- 💻 Code
- 📖 Documentation
- 🎨 Design
- 💡 Ideas & Planning
- 🧪 Testing
- 🐛 Bug Reports
- 👀 Code Reviews
- 📢 Evangelism
- 🌍 Translation
- 💬 Answering Questions
- 🚧 Maintenance
- 🔧 Tools
- 📦 Packaging

## 📚 Additional Resources

- [Development Guide](DEVELOPMENT.md) - Detailed development setup
- [Architecture Overview](docs/ARCHITECTURE.md) - How Flutter MCP works
- [API Reference](docs/API.md) - Server API documentation
- [Testing Guide](docs/TESTING.md) - How to write effective tests

## 🎯 Current Priorities

Check our [Project Board](https://github.com/adamsmaka/flutter-mcp/projects) for current priorities. Good first issues are labeled with [`good first issue`](https://github.com/adamsmaka/flutter-mcp/labels/good%20first%20issue).

### Quick Wins for New Contributors

- Fix typos or improve documentation clarity
- Add missing tests for existing functionality
- Improve error messages
- Add code examples to documentation
- Help triage issues

## 🚢 Release Process

We use semantic versioning and release regularly:

- **Patch releases** (x.x.1) - Bug fixes, documentation updates
- **Minor releases** (x.1.0) - New features, non-breaking changes
- **Major releases** (1.0.0) - Breaking changes (rare)

Releases are automated through GitHub Actions when maintainers tag a new version.

---

<p align="center">
  <strong>Ready to contribute?</strong>
  <br><br>
  Remember: no contribution is too small! Whether you're fixing a typo or adding a major feature, you're helping make AI + Flutter development better for everyone.
  <br><br>
  <strong>Thank you for being awesome! 🎉</strong>
  <br><br>
  Made with ❤️ by the Flutter MCP community
</p>
