CONTRIBUTING.mdā¢6.72 kB
# Contributing to ALA MCP Server
Thank you for your interest in contributing to the ALA MCP Server! This document provides guidelines and instructions for contributing.
## Code of Conduct
This project adheres to a Code of Conduct that all contributors are expected to follow. Please read [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) before contributing.
## Getting Started
### Prerequisites
- Python 3.10 or higher
- Git
- Virtual environment tool (venv)
### Setting Up Development Environment
1. Fork and clone the repository:
```bash
git clone https://github.com/yourusername/ala-mcp.git
cd ala-mcp
```
2. Create and activate a virtual environment:
```bash
python -m venv venv
source venv/bin/activate # On Windows: venv\Scripts\activate
```
3. Install development dependencies:
```bash
make install-dev
# or
pip install -e ".[dev]"
```
4. Install pre-commit hooks:
```bash
make pre-commit
# or
pre-commit install
```
## Development Workflow
### 1. Create a Branch
Create a feature branch for your changes:
```bash
git checkout -b feature/your-feature-name
# or
git checkout -b fix/your-bug-fix
```
Branch naming conventions:
- `feature/` - New features
- `fix/` - Bug fixes
- `docs/` - Documentation changes
- `refactor/` - Code refactoring
- `test/` - Test additions or fixes
### 2. Make Your Changes
- Write clear, concise code following the project's style guide
- Add tests for new functionality
- Update documentation as needed
- Keep commits atomic and well-described
### 3. Code Quality Checks
Before committing, ensure your code passes all checks:
```bash
# Format code
make format
# Run linting
make lint
# Run type checking
make type-check
# Run tests
make test
# Run all checks
make all
```
### 4. Commit Your Changes
Write clear commit messages following this format:
```
<type>: <subject>
<body>
<footer>
```
Types:
- `feat`: New feature
- `fix`: Bug fix
- `docs`: Documentation changes
- `style`: Formatting changes
- `refactor`: Code refactoring
- `test`: Test changes
- `chore`: Maintenance tasks
Example:
```
feat: add support for custom API endpoints
Allows users to configure custom API endpoints via environment
variables for testing against different ALA instances.
Closes #123
```
### 5. Push and Create Pull Request
```bash
git push origin feature/your-feature-name
```
Then create a pull request on GitHub with:
- Clear title describing the change
- Detailed description of what and why
- Reference to any related issues
- Screenshots if applicable
## Coding Standards
### Python Style Guide
We follow PEP 8 with these tools:
- **Black**: Code formatting (line length: 100)
- **Ruff**: Linting and import sorting
- **MyPy**: Type checking
### Code Organization
- Keep functions small and focused
- Use type hints for all function signatures
- Write docstrings for all public functions and classes
- Organize imports: standard library, third-party, local
Example:
```python
"""Module docstring describing the module's purpose."""
import asyncio
from typing import Dict, Optional
import httpx
from pydantic import BaseModel
from .config import settings
async def fetch_data(endpoint: str, params: Optional[Dict] = None) -> Dict:
"""
Fetch data from the API.
Args:
endpoint: API endpoint path
params: Optional query parameters
Returns:
Dict containing the response data
Raises:
httpx.HTTPError: If the request fails
"""
# Implementation
pass
```
### Testing Guidelines
- Write tests for all new functionality
- Aim for >90% code coverage
- Use descriptive test names
- Follow the Arrange-Act-Assert pattern
- Use fixtures for common test data
Example:
```python
@pytest.mark.asyncio
async def test_successful_request_returns_data(mock_client, sample_data):
"""Test that a successful request returns the expected data."""
# Arrange
client = ALAClient()
mock_client.request.return_value = sample_data
# Act
result = await client.request("GET", "/endpoint")
# Assert
assert result["status_code"] == 200
assert result["data"] == sample_data
```
## Pull Request Process
### Before Submitting
1. Ensure all tests pass
2. Update documentation
3. Add entry to CHANGELOG.md (if applicable)
4. Rebase on latest main branch
5. Verify CI checks will pass
### Review Process
1. At least one maintainer must review and approve
2. All CI checks must pass
3. Address all review comments
4. Maintainer will merge when ready
### After Merge
- Delete your feature branch
- Pull latest changes from main
- Celebrate your contribution! š
## Reporting Bugs
### Before Reporting
1. Check existing issues
2. Verify it's reproducible
3. Gather relevant information
### Bug Report Template
```markdown
**Description**
A clear description of the bug.
**To Reproduce**
Steps to reproduce the behavior:
1. Configure with '...'
2. Run command '...'
3. See error
**Expected Behavior**
What you expected to happen.
**Actual Behavior**
What actually happened.
**Environment**
- OS: [e.g., macOS 14.0]
- Python Version: [e.g., 3.11.5]
- Package Version: [e.g., 0.1.0]
**Additional Context**
Any other relevant information.
```
## Requesting Features
### Feature Request Template
```markdown
**Feature Description**
A clear description of the feature.
**Use Case**
Why is this feature needed? What problem does it solve?
**Proposed Solution**
How would you implement this feature?
**Alternatives Considered**
Other approaches you've considered.
**Additional Context**
Any other relevant information.
```
## Documentation
### Documentation Standards
- Use clear, concise language
- Provide examples for complex features
- Keep documentation up-to-date with code changes
- Use proper markdown formatting
### Building Documentation
```bash
# View README locally
make docs # (if implemented)
```
## Release Process
Maintainers follow this process for releases:
1. Update version in `pyproject.toml`
2. Update CHANGELOG.md
3. Create release commit
4. Tag release: `git tag -a v0.1.0 -m "Release 0.1.0"`
5. Push tag: `git push origin v0.1.0`
6. GitHub Actions automatically builds and creates release
## Getting Help
- **Questions**: Open a GitHub Discussion
- **Bugs**: Open a GitHub Issue
- **Security**: Email security@example.com (private)
- **Chat**: Join our Discord/Slack (if available)
## Recognition
Contributors are recognized in:
- GitHub contributors page
- CHANGELOG.md for significant contributions
- Release notes
## License
By contributing, you agree that your contributions will be licensed under the MIT License.
## Thank You!
Your contributions help make this project better for everyone. We appreciate your time and effort!