Northern-Thailand-Ping-River-Monitor/CONTRIBUTING.md

Contributing to Northern Thailand Ping River Monitor

Thank you for your interest in contributing to the Northern Thailand Ping River Monitor! This document provides guidelines and information for contributors.

🚀 Getting Started

Prerequisites

• Python 3.9 or higher
• Git
• Basic knowledge of water monitoring systems
• Familiarity with FastAPI and time-series databases (optional)

Development Setup

1. Clone the repository:

   git clone https://git.b4l.co.th/B4L/Northern-Thailand-Ping-River-Monitor.git
   cd Northern-Thailand-Ping-River-Monitor
   

2. Create a virtual environment:

   python -m venv venv
   source venv/bin/activate  # On Windows: venv\Scripts\activate
   

3. Install dependencies:

   pip install -r requirements.txt
   

4. Run tests:

   python test_integration.py
   

5. Start the development server:

   python run.py --web-api
   

🔧 Development Guidelines

Code Style

• Follow PEP 8 Python style guidelines
• Use type hints for all function parameters and return values
• Write descriptive docstrings for all classes and functions
• Keep functions focused and under 50 lines when possible

Testing

• Write tests for new features
• Ensure all existing tests pass before submitting
• Test both success and error cases
• Include integration tests for API endpoints

Documentation

• Update README.md for new features
• Add docstrings to all new functions and classes
• Update API documentation for new endpoints
• Include examples in documentation

📝 Contribution Process

1. Issue Creation

• Check existing issues before creating new ones
• Use clear, descriptive titles
• Provide detailed descriptions with steps to reproduce (for bugs)
• Include system information and logs when relevant

2. Pull Request Process

1. Fork the repository
2. Create a feature branch:

   git checkout -b feature/your-feature-name
   

3. Make your changes
4. Test thoroughly:

   python test_integration.py
   python test_station_management.py
   

5. Commit with clear messages:

   git commit -m "Add: New station validation feature"
   

6. Push to your fork:

   git push origin feature/your-feature-name
   

7. Create a pull request

Pull Request Guidelines

• Use clear, descriptive titles
• Provide detailed descriptions of changes
• Reference related issues
• Include screenshots for UI changes
• Ensure all tests pass
• Update documentation as needed

🎯 Areas for Contribution

High Priority

• Additional Database Support - MongoDB, TimescaleDB
• Authentication System - User management and API keys
• Real-time Alerts - Email/SMS notifications for critical conditions
• Mobile App - React Native or Flutter interface
• Advanced Analytics - Trend analysis and forecasting

Medium Priority

• Bulk Station Operations - Import/export multiple stations
• Map Interface - Visual station management
• Data Export - CSV, Excel format support
• Performance Optimization - Query optimization and caching
• Internationalization - Multi-language support

Low Priority

• Additional Visualizations - Custom chart types
• Report Generation - Automated PDF reports
• Integration APIs - Third-party service connections
• Advanced Logging - Structured logging with ELK stack

🐛 Bug Reports

When reporting bugs, please include:

1. Environment Information:

   • Operating system and version
   • Python version
   • Database type and version
   • Browser (for web interface issues)

2. Steps to Reproduce:

   • Clear, numbered steps
   • Expected vs actual behavior
   • Screenshots or error messages

3. Additional Context:

   • Log files (sanitized of sensitive data)
   • Configuration details
   • Recent changes to the system

💡 Feature Requests

For feature requests, please provide:

1. Use Case: Why is this feature needed?
2. Description: What should the feature do?
3. Acceptance Criteria: How do we know it's complete?
4. Priority: How important is this feature?
5. Alternatives: Are there workarounds available?

🔒 Security

Reporting Security Issues

• DO NOT create public issues for security vulnerabilities
• Email security issues to: [security contact]
• Include detailed information about the vulnerability
• Allow time for fixes before public disclosure

Security Guidelines

• Never commit sensitive data (passwords, API keys)
• Use environment variables for configuration
• Validate all user inputs
• Follow OWASP security guidelines
• Keep dependencies updated

📊 Database Contributions

Adding New Database Support

1. Create adapter in src/database_adapters.py
2. Implement all required methods
3. Add configuration options in src/config.py
4. Update documentation
5. Add integration tests

Database Schema Changes

• Provide migration scripts
• Test with existing data
• Document breaking changes
• Update all database adapters

🌐 API Contributions

Adding New Endpoints

1. Define Pydantic models in src/models.py
2. Implement endpoint in src/web_api.py
3. Add input validation
4. Include error handling
5. Write comprehensive tests
6. Update API documentation

API Guidelines

• Use RESTful conventions
• Include proper HTTP status codes
• Provide clear error messages
• Support pagination for large datasets
• Include rate limiting considerations

📈 Performance Guidelines

Optimization Areas

• Database query efficiency
• API response times
• Memory usage
• Concurrent request handling
• Data processing speed

Monitoring

• Use built-in metrics collection
• Monitor response times
• Track error rates
• Watch resource usage
• Set up alerts for issues

🧪 Testing Guidelines

Test Types

• Unit Tests: Individual function testing
• Integration Tests: Component interaction testing
• API Tests: Endpoint functionality testing
• Performance Tests: Load and stress testing

Test Coverage

• Aim for >80% code coverage
• Test both success and failure paths
• Include edge cases
• Test with different database backends

📚 Documentation Standards

Code Documentation

• Use clear, descriptive variable names
• Write comprehensive docstrings
• Include type hints
• Add inline comments for complex logic

User Documentation

• Keep README.md updated
• Provide clear installation instructions
• Include usage examples
• Document configuration options

🤝 Community Guidelines

Communication

• Be respectful and professional
• Help newcomers get started
• Share knowledge and experiences
• Provide constructive feedback

Code Reviews

• Review code thoroughly
• Provide specific, actionable feedback
• Be open to suggestions
• Focus on code quality and maintainability

📞 Getting Help

Resources

• Documentation: README.md and docs/
• API Reference: http://localhost:8000/docs
• Issues: GitHub Issues section
• Discussions: GitHub Discussions

Contact

• General Questions: Create a GitHub issue
• Security Issues: [security contact]
• Maintainer: [maintainer contact]

🎉 Recognition

Contributors will be recognized in:

• README.md contributors section
• Release notes for significant contributions
• Special recognition for major features

Thank you for contributing to the Northern Thailand Ping River Monitor! Your contributions help improve water resource monitoring and management in the region.