Contributing to Daflip ¶

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

Development Setup ¶

Prerequisites ¶

Python 3.9 or higher
Git
uv

Getting Started ¶

Fork and clone the repository

git clone https://github.com/your-username/daflip.git
cd daflip

Install dependencies

# With uv (recommended)
uv sync --dev

# With pip
pip install -e ".[dev]"

Install pre-commit hooks
```
pre-commit install
```

Verify setup

pytest
ruff check .
pre-commit run --all-files

Development Workflow ¶

1. Create a Feature Branch ¶

git checkout -b feature/your-feature-name

2. Make Your Changes ¶

Write your code
Add tests for new functionality
Update documentation if needed

3. Run Tests ¶

# Run all tests
pytest

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

# Run specific test file
pytest tests/test_services.py

# Run linting
ruff check .
ruff format .

4. Commit Your Changes ¶

git add .
git commit -m "feat: add new feature description"

5. Push and Create Pull Request ¶

git push origin feature/your-feature-name

Then create a pull request on GitHub.

Code Style ¶

We use Ruff for linting and formatting.

Running Ruff ¶

# Check for issues
ruff check .

# Fix auto-fixable issues
ruff check . --fix

# Format code
ruff format .

Pre-commit Hooks ¶

We use pre-commit hooks to ensure code quality and consistency. The hooks run automatically before each commit and include:

Code formatting with Ruff
Linting with Ruff
Type checking with MyPy
Basic file checks (trailing whitespace, YAML validation, etc.)

Setup ¶

# Install pre-commit
uv add pre-commit

# Install the git hooks
uv run pre-commit install

Usage ¶

The hooks run automatically on commit, but you can also run them manually:

# Run all hooks on all files
uv run pre-commit run --all-files

# Run specific hook
uv run pre-commit run ruff --all-files

# Run hooks on staged files only
pre-commit run

## Testing

### Running Tests

```bash
# All tests
uv run pytest

# With coverage
uv run pytest --cov=src/daflip --cov-report=html

# Specific test
uv run pytest tests/test_services.py::test_convert_roundtrip

# Verbose output
uv run pytest -v

Writing Tests ¶

Tests should be in the tests/ directory
Use descriptive test names
Test both success and failure cases
Use pytest fixtures for common setup

Test Structure ¶

def test_feature_name():
    """Test description."""
    # Arrange
    input_data = "test"

    # Act
    result = function_to_test(input_data)

    # Assert
    assert result == expected_output

Documentation ¶

Building Documentation ¶

# Install docs dependencies
uv add mkdocs mkdocs-material

# Build docs
uv run mkdocs build

# Serve docs locally
uv run mkdocs serve

Documentation Guidelines ¶

Write clear, concise documentation
Include examples for all features
Update API documentation when changing functions
Use proper markdown formatting

Pull Request Guidelines ¶

Before Submitting ¶

Tests pass: All tests should pass
Linting passes: No ruff errors
Documentation updated: Update docs for new features
Commit messages: Use conventional commit format

Commit Message Format ¶

type(scope): description

[optional body]

[optional footer]

Types: - feat: New feature - fix: Bug fix - docs: Documentation changes - style: Code style changes - refactor: Code refactoring - test: Test changes - chore: Build/tooling changes

Examples:

feat(services): add support for new file format
fix(cli): handle missing input file gracefully
docs(api): update CLI reference with new options

Pull Request Template ¶

When creating a PR, include:

Description of changes
Related issue (if any)
Testing performed
Breaking changes (if any)

Getting Help ¶

Issues: Use GitHub issues for bugs and feature requests
Discussions: Use GitHub discussions for questions
Code Review: All PRs require review before merging

Release Process ¶

The project uses automated semantic releases based on commit messages:

Automated Releases ¶

Commit messages determine version bump:
feat: → minor version bump (0.1.0 → 0.2.0)
fix: → patch version bump (0.1.0 → 0.1.1)
BREAKING CHANGE or !: → major version bump (0.1.0 → 1.0.0)
GitHub Actions automatically:
Analyzes commit messages since last release
Updates version in pyproject.toml and src/daflip/__init__.py
Generates changelog
Creates and pushes a git tag
Creates a GitHub release
Publishes to PyPI
Requirements for automated releases:
Repository admin or PAT token with admin privileges
Branch protection rules configured to allow admin bypass
Conventional commit messages

Manual Release (if needed)¶

If automated releases fail:

Update version in pyproject.toml
Update version in src/daflip/__init__.py
Update changelog
Create release tag: git tag v0.1.0
Push tag: git push origin v0.1.0
GitHub Actions will build and publish

Thank you for contributing to Daflip! 🚀