| # Contributing to CleanCity Agent | |
| Thank you for your interest in contributing to CleanCity Agent! 🌍 | |
| ## 🎯 Project Vision | |
| CleanCity Agent aims to make environmental action accessible through AI-powered trash detection and cleanup planning. We welcome contributions that align with this mission. | |
| ## 🚀 Quick Start | |
| 1. **Fork the repository** | |
| 2. **Clone your fork:** | |
| ```bash | |
| git clone https://github.com/YOUR_USERNAME/CleanCity-Agent.git | |
| cd CleanCity-Agent | |
| ``` | |
| 3. **Create a virtual environment:** | |
| ```bash | |
| python -m venv venv | |
| source venv/bin/activate # On Windows: venv\Scripts\activate | |
| ``` | |
| 4. **Install dependencies:** | |
| ```bash | |
| pip install -r requirements.txt | |
| ``` | |
| 5. **Create a branch:** | |
| ```bash | |
| git checkout -b feature/your-feature-name | |
| ``` | |
| ## 📝 Development Guidelines | |
| ### Code Style | |
| - Follow **PEP 8** Python style guide | |
| - Use **type hints** for function parameters and returns | |
| - Add **docstrings** to all functions and classes | |
| - Keep functions small and focused (single responsibility) | |
| ### Testing Your Changes | |
| Before submitting a PR: | |
| 1. **Test the Gradio app:** | |
| ```bash | |
| python app.py | |
| ``` | |
| 2. **Test the MCP server:** | |
| ```bash | |
| python mcp_server.py | |
| ``` | |
| 3. **Verify all tabs work:** | |
| - Analysis tab | |
| - History tab | |
| - Impact & Examples tab | |
| - Chat tab | |
| 4. **Test with different LLM providers:** | |
| - Set `LLM_PROVIDER=offline` (default) | |
| - Test with real API keys if available | |
| ### Commit Messages | |
| Use clear, descriptive commit messages: | |
| ``` | |
| ✅ Good: | |
| - "Add GPS auto-detection feature" | |
| - "Fix model path resolution for deployed environments" | |
| - "Improve error handling in trash detection" | |
| ❌ Bad: | |
| - "Update stuff" | |
| - "Fix bug" | |
| - "WIP" | |
| ``` | |
| ## 🎨 Areas for Contribution | |
| ### High Priority | |
| - **Real YOLOv8 Model Integration** - Replace mock detector with trained model | |
| - **Mobile Responsiveness** - Improve UI for smartphones | |
| - **Multilingual Support** - Add i18n for global reach | |
| - **Performance Optimization** - Faster image processing | |
| - **Accessibility** - ARIA labels, keyboard navigation, screen reader support | |
| ### Feature Ideas | |
| - **Gamification** - Points/badges for cleanup reporting | |
| - **Community Features** - Team cleanup coordination | |
| - **Advanced Analytics** - Trend analysis, predictive hotspots | |
| - **Integration with City Services** - API for municipal waste management | |
| - **Offline Mode Enhancement** - PWA with offline detection | |
| ### Documentation | |
| - Additional usage examples | |
| - Tutorial videos | |
| - API documentation improvements | |
| - Translation of docs to other languages | |
| ## 🐛 Reporting Bugs | |
| Found a bug? Help us fix it! | |
| 1. **Check existing issues** to avoid duplicates | |
| 2. **Create a new issue** with: | |
| - Clear title describing the problem | |
| - Steps to reproduce | |
| - Expected vs. actual behavior | |
| - Screenshots if applicable | |
| - Your environment (OS, Python version, browser) | |
| **Template:** | |
| ```markdown | |
| ## Bug Description | |
| [What went wrong?] | |
| ## Steps to Reproduce | |
| 1. Go to... | |
| 2. Click on... | |
| 3. See error... | |
| ## Expected Behavior | |
| [What should happen?] | |
| ## Actual Behavior | |
| [What actually happens?] | |
| ## Environment | |
| - OS: [e.g., Windows 11, macOS 14] | |
| - Python: [e.g., 3.11.5] | |
| - Browser: [e.g., Chrome 120] | |
| ``` | |
| ## 💡 Feature Requests | |
| Have an idea? We'd love to hear it! | |
| 1. **Open an issue** with the `enhancement` label | |
| 2. **Describe the feature:** | |
| - What problem does it solve? | |
| - Who would benefit? | |
| - How should it work? | |
| 3. **Optional:** Include mockups, diagrams, or code sketches | |
| ## 🔀 Pull Request Process | |
| 1. **Ensure your code works** (see Testing section above) | |
| 2. **Update documentation** if you changed functionality | |
| 3. **Update README.md** if you added features | |
| 4. **Create a pull request:** | |
| - Descriptive title | |
| - Summary of changes | |
| - Link to related issues | |
| - Screenshots if UI changed | |
| ### PR Checklist | |
| - [ ] Code follows PEP 8 style | |
| - [ ] Added type hints | |
| - [ ] Added/updated docstrings | |
| - [ ] Tested locally (app runs without errors) | |
| - [ ] Updated relevant documentation | |
| - [ ] No sensitive data (API keys, passwords) committed | |
| ## 📜 Code of Conduct | |
| ### Our Pledge | |
| We are committed to providing a welcoming and inclusive environment for everyone. | |
| ### Expected Behavior | |
| - **Be respectful** and considerate in all interactions | |
| - **Be constructive** when giving feedback | |
| - **Be patient** with newcomers | |
| - **Focus on the mission** - cleaner cities and environmental action | |
| ### Unacceptable Behavior | |
| - Harassment, discrimination, or personal attacks | |
| - Trolling or inflammatory comments | |
| - Spam or self-promotion unrelated to the project | |
| **Violations:** Contact project maintainers. Violators may be banned. | |
| ## 🏆 Recognition | |
| Contributors will be: | |
| - Listed in README acknowledgments | |
| - Credited in release notes | |
| - Given proper attribution in commits | |
| ## ❓ Questions? | |
| - **GitHub Issues:** For bugs and features | |
| - **Discussions:** For questions and ideas | |
| - **Email:** [Contact project maintainer if email available] | |
| --- | |
| **Thank you for helping make CleanCity Agent better! 🌱** | |
| Your contributions help communities worldwide take action against litter and pollution. | |