unitforge/CONTRIBUTING.md

Contributing to UnitForge

Thank you for your interest in contributing to UnitForge! This guide will help you get started with development and understand our project workflow.

🏗️ Project Overview

UnitForge is a comprehensive tool for creating, validating, and managing Linux systemd unit files.

• Stage: Development
• Production: Not in production
• Compatibility: No backward compatibility requirements during development
• Principle: Keep it small and simple

🚀 Quick Start

Prerequisites

• Python 3.11+
• uv package manager
• Git

Setup Development Environment

# Clone the repository
git clone <repository-url>
cd unitforge

# Quick setup (recommended)
make setup-dev

# Manual setup
uv venv
source .venv/bin/activate
uv pip install -e ".[dev,web]"

Essential Commands

Task	Command
Setup environment	make setup-dev
Run server	make server
Run tests	make test
Run tests with coverage	make test-cov
Lint and format	make lint && make format
Full dev cycle	make dev

📋 Development Rules

Core Principles

1. Fix lint errors - Code must always pass lint checks
2. Keep code lean - Avoid unnecessary abstractions; keep it direct
3. Keep tests consistent - All tests must pass; write tests for new code
4. Remove legacy code - Delete or refactor outdated code
5. Use Makefile for services - Prefer make targets to run and manage services

Technical Requirements

• Server: uvicorn
• Package Manager: uv (never use pip)
• Python Standard: PEP 8
• Type Hints: Required for all new code
• Formatter: Black
• Code Quality: No duplication, high cohesion, minimal complexity

🔄 Development Workflow

1. Setting Up for a New Feature

# Update your local repository
git pull origin main

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

# Set up development environment
make setup-dev

2. Development Cycle

# Make your changes...

# Run the full development cycle
make dev  # This runs: format + lint + test

# Or run individually:
make format  # Format code with Black
make lint    # Run linting checks
make test    # Run test suite

3. Testing Your Changes

# Run specific tests
make test

# Run with coverage
make test-cov

# Test the web interface
make server
# Visit http://localhost:8000

# Test CLI functionality
./unitforge-cli --help

4. Quality Checks

Before committing, ensure all quality checks pass:

# All-in-one quality check
make dev

# Individual checks
make lint     # flake8, black --check, isort --check
make format   # black, isort
make test     # pytest

5. Submitting Changes

# Add and commit your changes
git add .
git commit -m "feat: add amazing new feature"

# Push your branch
git push origin feature/your-feature-name

# Create a pull request

🧪 Testing Guidelines

Writing Tests

• Place tests in the tests/ directory
• Use pytest for all testing
• Follow the existing test patterns
• Include both unit and integration tests

Test Structure

def test_feature_behavior():
    """Test that feature behaves correctly."""
    # Arrange
    setup_test_data()

    # Act
    result = call_feature()

    # Assert
    assert result.is_valid()

Running Tests

# All tests
make test

# With coverage report
make test-cov

# Specific test file
uv run pytest tests/test_specific.py -v

# Watch mode (re-run on changes)
make test-watch

🎨 Code Style

Python Style Guidelines

• Follow PEP 8 strictly
• Use type hints for all functions and methods
• Format with Black (automatic via pre-commit)
• Sort imports with isort (automatic via pre-commit)

Example Code Style

from typing import Optional, List
from pathlib import Path

def process_unit_file(
    file_path: Path,
    validate: bool = True,
    options: Optional[List[str]] = None
) -> bool:
    """Process a systemd unit file.

    Args:
        file_path: Path to the unit file
        validate: Whether to validate the file
        options: Additional processing options

    Returns:
        True if processing succeeded

    Raises:
        FileNotFoundError: If the file doesn't exist
        ValidationError: If validation fails
    """
    if options is None:
        options = []

    # Implementation...
    return True

Code Organization

• High cohesion: Keep related functionality together
• Low coupling: Minimize dependencies between modules
• Minimal complexity: Prefer simple, readable code
• No duplication: Extract common functionality

🏗️ Architecture Guidelines

Project Structure

unitforge/
├── backend/           # Python backend
│   ├── app/          # FastAPI application
│   ├── cli/          # CLI implementation
│   └── requirements.txt
├── frontend/         # Web interface
│   ├── static/       # CSS, JS, assets
│   └── templates/    # HTML templates
├── tests/            # Test suite
├── scripts/          # Utility scripts
└── docs/             # Documentation

Adding New Features

1. Backend Features: Add to backend/app/
2. CLI Features: Add to backend/cli/
3. Templates: Add to backend/app/templates/
4. Tests: Add to tests/
5. Documentation: Update relevant docs

API Development

• Use FastAPI for all API endpoints
• Follow REST conventions
• Include comprehensive error handling
• Add API documentation with docstrings

🐳 Docker Development

Docker Commands

# Build containers
make docker-build

# Run development environment
make docker-dev

# Run production environment
make docker-prod

# Clean up
make docker-clean

Container Registry

# Build and push to registry
make registry-push

# Login to registry
make docker-login

🔧 Debugging

Common Issues

Import Errors:

# Ensure you're in the virtual environment
source .venv/bin/activate

# Reinstall in development mode
uv pip install -e ".[dev,web]"

Test Failures:

# Run tests with verbose output
make test -v

# Run specific failing test
uv run pytest tests/test_failing.py::test_function -v

Linting Errors:

# Auto-fix formatting issues
make format

# Check what lint issues remain
make lint

Development Tools

# Start development server with hot reload
make server

# Open interactive Python shell with project context
uv run python

# Run CLI in development mode
./unitforge-cli --help

📖 Documentation

Updating Documentation

• Update relevant documentation when adding features
• Follow existing documentation patterns
• Include code examples for new APIs
• Test documentation examples

Documentation Files

• README.md - Main project documentation
• docs/ENVIRONMENT.md - Environment configuration
• CONTRIBUTING.md - This file
• docker/README.md - Docker-specific documentation
• scripts/README.md - Utility scripts documentation

🚀 Release Process

Version Management

UnitForge uses semantic versioning (SemVer):

• MAJOR.MINOR.PATCH
• Major: Breaking changes
• Minor: New features
• Patch: Bug fixes

Pre-release Checklist

• All tests pass (make test)
• No linting errors (make lint)
• Documentation updated
• Version bumped in pyproject.toml
• CHANGELOG updated

🤝 Community Guidelines

Code of Conduct

• Be respectful and inclusive
• Help others learn and contribute
• Focus on constructive feedback
• Celebrate different perspectives

Getting Help

1. Check existing documentation in docs/
2. Search existing issues on GitHub
3. Run the demo with ./demo.sh
4. Ask questions in GitHub discussions
5. Report bugs with detailed reproduction steps

Issue Reporting

When reporting bugs, please include:

• Operating system and version
• Python version
• uv version
• Steps to reproduce
• Expected vs actual behavior
• Relevant log output

Feature Requests

For feature requests:

• Check existing issues for duplicates
• Describe the use case clearly
• Provide examples if possible
• Consider implementation complexity
• Align with project principles

🔗 Useful Links

• Main Repository: [GitHub Repository URL]
• Issue Tracker: [GitHub Issues URL]
• API Documentation: http://localhost:8000/api/docs (when running)
• systemd Documentation: https://systemd.io/

🎯 Next Steps

1. Set up your development environment with make setup-dev
2. Run the tests to ensure everything works: make test
3. Try the web interface: make server
4. Explore the CLI: ./unitforge-cli --help
5. Read the code in backend/app/ to understand the architecture
6. Look at existing tests in tests/ for examples
7. Check open issues for contribution opportunities

Welcome to the UnitForge community! 🚀

---

This guide is a living document. Please help keep it up-to-date as the project evolves.