Contributing¶

Thank you for your interest in contributing to Blacklake! This guide will help you get started.

Development Workflow¶

1. Fork and Clone¶

# Fork the repository on GitHub
# Then clone your fork
git clone https://github.com/your-username/blacklake.git
cd blacklake

2. Set Up Development Environment¶

# Install development dependencies
uv pip install -e ".[dev,server,docs]"

# Install pre-commit hooks
pre-commit install

# Start services
docker-compose up -d

3. Make Changes¶

# Create a feature branch
git checkout -b feature/your-feature

# Make your changes
# ... edit code ...

# Run tests
pytest

# Run linting
ruff check src/
mypy src/

# Run pre-commit checks
pre-commit run --all-files

4. Submit Pull Request¶

# Commit your changes
git add .
git commit -m "feat: add your feature"

# Push to your fork
git push origin feature/your-feature

# Create pull request on GitHub

Code Style¶

Python Code¶

Formatting: Use ruff for linting and formatting
Type Hints: Use type hints for all functions
Docstrings: Use Google-style docstrings
Imports: Sort imports with isort

Pre-commit Hooks¶

The following hooks are configured:

ruff - Linting and formatting
mypy - Type checking
codespell - Spell checking
pre-commit-hooks - General checks

Example Code Style¶

def process_metadata(
    metadata: Dict[str, Any],
    validate: bool = True
) -> Optional[Dict[str, Any]]:
    """Process metadata with optional validation.

    Args:
        metadata: The metadata dictionary to process
        validate: Whether to validate the metadata

    Returns:
        Processed metadata or None if validation fails

    Raises:
        ValidationError: If validation fails and validate=True
    """
    if validate:
        if not _validate_metadata(metadata):
            raise ValidationError("Invalid metadata")

    return _process_metadata(metadata)

Testing¶

Running Tests¶

# Run all tests
pytest

# Run specific test file
pytest tests/test_cli.py

# Run with coverage
pytest --cov=src/blacklake

# Run with verbose output
pytest -v

Writing Tests¶

def test_metadata_validation():
    """Test metadata validation."""
    metadata = {
        "title": "Test Dataset",
        "creator": {"name": "Test User"},
        "created": "2024-01-15T10:30:00Z"
    }

    result = validate_metadata(metadata)
    assert result is True

Documentation¶

Building Documentation¶

# Install documentation dependencies
pip install -r requirements-docs.txt

# Generate CLI docs
python scripts/docs/gen_cli_docs.py

# Export OpenAPI spec
python scripts/docs/export_openapi.py

# Build documentation
mkdocs build

# Serve locally
mkdocs serve

Writing Documentation¶

Use clear, concise language
Include code examples with expected output
Use Mermaid diagrams for complex workflows
Follow the existing structure and style

Pull Request Guidelines¶

Before Submitting¶

PR Description¶

Include:

Summary: Brief description of changes
Type: feat, fix, docs, refactor, test
Breaking Changes: List any breaking changes
Testing: How to test the changes
Screenshots: For UI changes

Example PR Description¶

## Summary
Add support for custom metadata validation rules.

## Type
feat

## Changes
- Add `ValidationRule` class for custom rules
- Extend `MetadataManager` with rule support
- Add CLI command `meta validate --rules`

## Testing
```bash
blacklake meta validate --rules custom-rules.json

Breaking Changes¶

None

## Issue Guidelines

### Before Creating an Issue

- Search existing issues
- Check if it's a duplicate
- Verify it's not a configuration issue

### Issue Template

```markdown
## Description
Brief description of the issue.

## Steps to Reproduce
1. Step one
2. Step two
3. Step three

## Expected Behavior
What should happen.

## Actual Behavior
What actually happens.

## Environment
- OS: [e.g., macOS 13.0]
- Python: [e.g., 3.12.0]
- Blacklake: [e.g., 0.1.0]

## Additional Context
Any other relevant information.

Release Process¶

Version Bumping¶

We use Commitizen for version management:

# Bump version
cz bump

# Or specify version
cz bump --version 0.2.0

Release Checklist¶

Community Guidelines¶

Code of Conduct¶

Be respectful and inclusive
Focus on constructive feedback
Help others learn and grow
Follow the Code of Conduct

Getting Help¶

GitHub Discussions: For questions and discussions
GitHub Issues: For bug reports and feature requests
Documentation: Check the docs first

Recognition¶

Contributors are recognized in:

README: Listed as contributors
Changelog: Mentioned in release notes
Documentation: Credited in relevant sections

Next Steps¶

Code of Conduct - Community guidelines
Roadmap - Future development plans
FAQ - Frequently asked questions