# Contributing to Chatlog MCP Server
Thank you for your interest in contributing to Chatlog MCP Server! This document provides guidelines for contributing to the project.
## 📋 Table of Contents
- [Code of Conduct](#code-of-conduct)
- [Getting Started](#getting-started)
- [Development Workflow](#development-workflow)
- [Coding Standards](#coding-standards)
- [Testing](#testing)
- [Submitting Changes](#submitting-changes)
- [Reporting Issues](#reporting-issues)
## 🤝 Code of Conduct
By participating in this project, you agree to abide by our Code of Conduct. Please read it before contributing.
## 🚀 Getting Started
### Prerequisites
- Python 3.10 or higher
- pip
- git
### Setup Development Environment
1. Fork the repository on GitHub
2. Clone your fork:
```bash
git clone https://github.com/YOUR_USERNAME/chatlog-mcp-server.git
cd chatlog-mcp-server
```
3. Create a virtual environment:
```bash
python -m venv venv
source venv/bin/activate # On Windows: venv\Scripts\activate
```
4. Install in development mode:
```bash
pip install -e ".[dev]"
```
5. Verify installation:
```bash
chatlog-mcp --version
```
## 🔄 Development Workflow
### Branch Naming
Use descriptive branch names:
- `feature/descriptive-name` for new features
- `bugfix/issue-description` for bug fixes
- `docs/update-readme` for documentation updates
### Commit Messages
Follow conventional commit format:
```
type(scope): description
Examples:
feat: add keyword search functionality
fix: handle empty chatlog data
docs: update installation instructions
test: add unit tests for server module
```
Types:
- `feat`: New feature
- `fix`: Bug fix
- `docs`: Documentation
- `test`: Testing
- `refactor`: Code refactoring
- `style`: Code style changes
- `perf`: Performance improvements
### Pull Request Process
1. Create a feature branch from `main`
2. Make your changes
3. Write or update tests
4. Ensure all tests pass: `pytest`
5. Update documentation if needed
6. Commit your changes with a clear message
7. Push to your fork
8. Create a Pull Request
## 📝 Coding Standards
### Python Code Style
We follow PEP 8 with some modifications:
- Line length: 88 characters (Black default)
- Use Black for formatting
- Use isort for import sorting
- Use flake8 for linting
### Code Formatting
Run before committing:
```bash
black chatlog_mcp/
isort chatlog_mcp/
flake8 chatlog_mcp/
```
### Type Hints
Use type hints for all function parameters and return values:
```python
from typing import List, Dict, Optional
def process_messages(messages: List[Dict[str, Any]]) -> Dict[str, int]:
"""Process a list of messages."""
pass
```
### Documentation
- Use docstrings for all public functions and classes
- Follow Google style docstrings:
```python
def get_chatlog(time: str, talker: str) -> List[Dict[str, Any]]:
"""Get chat logs for a specific time and chatroom.
Args:
time: Time range in format 'YYYY-MM-DD' or 'YYYY-MM-DD~YYYY-MM-DD'
talker: Chatroom or contact ID
Returns:
List of message dictionaries
Raises:
ValueError: If time format is invalid
"""
pass
```
## 🧪 Testing
### Running Tests
Run all tests:
```bash
pytest
```
Run specific test file:
```bash
pytest chatlog_mcp/tests/test_server.py
```
Run with coverage:
```bash
pytest --cov=chatlog_mcp
```
### Writing Tests
- Write tests for all new features
- Use descriptive test names
- Follow Arrange-Act-Assert pattern:
```python
@pytest.mark.asyncio
async def test_list_chatrooms_with_keyword():
"""Test that list_chatrooms filters by keyword."""
# Arrange
keyword = "test"
# Act
result = await handle_list_chatrooms(keyword=keyword)
# Assert
assert len(result) > 0
# ... more assertions
```
### Test Coverage
Aim for:
- Minimum 80% code coverage
- All new features must have tests
- All bug fixes must have regression tests
## 📦 Submitting Changes
### Before Submitting
1. Run all tests: `pytest`
2. Check code style: `flake8 chatlog_mcp/`
3. Format code: `black chatlog_mcp/`
4. Update documentation
5. Add/update tests
### Pull Request Template
Use the provided PR template:
```markdown
## Description
Brief description of changes
## Type of Change
- [ ] Bug fix
- [ ] New feature
- [ ] Documentation update
- [ ] Performance improvement
## Testing
- [ ] Tests pass locally
- [ ] Added/updated tests
- [ ] Manual testing performed
## Checklist
- [ ] Code follows style guidelines
- [ ] Self-review completed
- [ ] Documentation updated
- [ ] Tests added/updated
```
### Review Process
All PRs require:
1. At least one maintainer review
2. All CI checks passing
3. Code coverage not decreased
4. Documentation updated (if applicable)
## 🐛 Reporting Issues
### Before Reporting
1. Check existing issues
2. Search for similar problems
3. Try the latest version
4. Test with minimal example
### Issue Template
```markdown
**Describe the bug**
A clear description of the bug
**Environment**
- OS: [e.g., Ubuntu 20.04]
- Python version: [e.g., 3.10.5]
- Package version: [e.g., 1.0.0]
**Reproduction Steps**
1. Go to '...'
2. Click on '....'
3. Scroll down to '....'
4. See error
**Expected behavior**
What you expected to happen
**Actual behavior**
What actually happened
**Logs**
If applicable, paste relevant log output
```
## 💡 Feature Requests
### Before Requesting
1. Check if feature already exists
2. Consider if it's in scope
3. Think about implementation
### Feature Request Template
```markdown
**Is your feature request related to a problem?**
A clear description of what the problem is
**Describe the solution you'd like**
A clear description of what you want to happen
**Describe alternatives you've considered**
A clear description of any alternative solutions
**Use Case**
Describe who would use this feature and why
```
## 📚 Resources
- [Python Developer's Guide](https://devguide.python.org/)
- [pytest Documentation](https://docs.pytest.org/)
- [Black Code Style](https://black.readthedocs.io/)
- [MCP Specification](https://modelcontextprotocol.io/)
## ❓ Questions?
Feel free to:
- Open an issue for questions
- Join our discussions
- Contact maintainers
Thank you for contributing! 🎉
