Contributing¶

Welcome! This guide helps you contribute to Machineuse.

Getting Started¶

Prerequisites¶

Python 3.11+
Poetry
Git
Ubuntu/Debian (for full testing)

Setup¶

# Clone the repository
git clone https://github.com/dotcommoners/machineuse.git
cd machineuse

# Install dependencies
cd machineuse-api
poetry install --with dev

# Activate virtual environment
poetry shell

Verify Setup¶

# Run tests
poetry run pytest

# Run linting
poetry run flake8 machineuse tests
poetry run mypy machineuse

Development Workflow¶

1. Create a Branch¶

git checkout -b feature/your-feature-name

Branch naming conventions: - feature/ — New features - fix/ — Bug fixes - docs/ — Documentation changes - refactor/ — Code refactoring - test/ — Test additions

2. Make Changes¶

Write your code following our Code Style guide.

3. Write Tests¶

Add tests for new functionality:

# Run tests
poetry run pytest

# With coverage
poetry run pytest --cov=machineuse

# Specific test file
poetry run pytest tests/test_your_feature.py -v

4. Format and Lint¶

# Format code
poetry run black machineuse tests
poetry run isort machineuse tests

# Lint
poetry run flake8 machineuse tests
poetry run mypy machineuse

5. Commit Changes¶

Write clear commit messages:

git add .
git commit -m "feat: Add snapshot compression support

Implement gzip compression for snapshots to reduce storage.
Compression level is configurable via environment variable.

Closes #123"

6. Submit Pull Request¶

Push your branch: git push origin feature/your-feature-name
Open a PR on GitHub
Fill in the PR template
Wait for review

Code of Conduct¶

We expect all contributors to:

Be respectful and inclusive
Provide constructive feedback
Focus on the best outcome for the project
Help others learn and grow

Pull Request Guidelines¶

PR Title¶

Use conventional commit format:

type: short description

Examples:
feat: Add distributed scheduling support
fix: Resolve container cleanup race condition
docs: Update installation guide
refactor: Simplify messaging client

PR Description¶

Include:

Summary: What does this PR do?
Motivation: Why is this change needed?
Changes: List of changes made
Testing: How was this tested?
Checklist: Standard checks completed

PR Template¶

## Summary
Brief description of changes.

## Motivation
Why this change is needed.

## Changes
- Change 1
- Change 2

## Testing
How the changes were tested.

## Checklist
- [ ] Tests added/updated
- [ ] Documentation updated
- [ ] Code formatted and linted
- [ ] Self-reviewed

Review Process¶

Automated Checks: CI runs tests and linting
Code Review: Maintainer reviews changes
Feedback: Address any requested changes
Approval: Maintainer approves PR
Merge: PR is merged to main

Types of Contributions¶

Bug Reports¶

Search existing issues first
Use the bug report template
Include reproduction steps
Provide system information

Feature Requests¶

Search existing issues first
Use the feature request template
Explain the use case
Discuss implementation ideas

Documentation¶

Fix typos and errors
Improve explanations
Add examples
Translate content

Code¶

Bug fixes
New features
Performance improvements
Refactoring

Development Tips¶

Running the API Server¶

# Development mode with auto-reload
poetry run uvicorn machineuse.api.server:app --reload --host 0.0.0.0 --port 8000

Testing Without Containers¶

For testing without systemd-nspawn:

from unittest.mock import patch, MagicMock

@patch('subprocess.run')
def test_container_creation(mock_subprocess):
    mock_subprocess.return_value = MagicMock(returncode=0)
    # Your test code

Debugging¶

# Enable debug logging
export MACHINEUSE_LOG_LEVEL=DEBUG

# Run with debugger
poetry run python -m debugpy --listen 5678 -m machineuse.api.server

Getting Help¶

Questions: Open a discussion on GitHub
Bugs: Open an issue with the bug template
Chat: Join our community chat (if available)

Recognition¶

Contributors are recognized in:

CONTRIBUTORS file
Release notes
Documentation

Thank you for contributing!