compose/CONTRIBUTING.md

Contributing to Compose

Thank you for your interest in contributing to the Compose project! This document provides guidelines and information for contributors.

Development Setup

1. Clone the repository:

   git clone <repository-url>
   cd compose
   

2. Install development dependencies:

   uv pip install -e ".[dev]"
   

3. Install pre-commit hooks:

   make pre-commit-install
   

Development Workflow

Code Quality

We use several tools to maintain code quality:

• Ruff: For linting and formatting
• MyPy: For type checking
• Pre-commit: For automated checks on commit

Running Checks

# Run all checks
make check-all

# Run individual checks
make lint          # Linting
make format        # Code formatting
make type-check    # Type checking
make test          # Tests
make test-cov      # Tests with coverage

Pre-commit Hooks

Pre-commit hooks will automatically run on each commit. To run them manually:

make pre-commit-run

Testing

Running Tests

# Run all tests
make test

# Run tests with coverage
make test-cov

# Run specific test file
uv run pytest tests/test_specific.py

# Run tests with verbose output
uv run pytest -v

Writing Tests

• Place all tests in the tests/ directory
• Use descriptive test names
• Follow the existing test patterns
• Include both positive and negative test cases
• Test edge cases and error conditions

Code Style

Python Code

• Follow PEP 8 style guidelines
• Use type hints for all function parameters and return values
• Write docstrings for all public functions and classes
• Use Google-style docstrings

Commit Messages

• Use clear, descriptive commit messages
• Start with a verb in present tense (e.g., "Add", "Fix", "Update")
• Keep the first line under 50 characters
• Add more details in the body if needed

Example:

Add support for Docker Compose volumes

- Implement VolumeConfig class
- Add add_volume and remove_volume methods
- Include comprehensive tests

Pull Request Process

1. Create a feature branch from the main branch
2. Make your changes following the coding guidelines
3. Write tests for new functionality
4. Run all checks to ensure code quality
5. Update documentation if needed
6. Submit a pull request with a clear description

Pull Request Checklist

• Code follows the project's style guidelines
• Tests pass and coverage is maintained
• Documentation is updated
• Pre-commit hooks pass
• Type checking passes
• Linting passes

Reporting Issues

When reporting issues, please include:

• A clear description of the problem
• Steps to reproduce the issue
• Expected behavior
• Actual behavior
• Environment details (Python version, OS, etc.)
• Any relevant error messages or logs

Getting Help

If you need help or have questions:

• Check the existing documentation
• Look at existing issues and pull requests
• Create a new issue for bugs or feature requests
• Ask questions in discussions

License

By contributing to this project, you agree that your contributions will be licensed under the same license as the project.