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](https://github.com/astral-sh/uv) package manager
- Git

### Setup Development Environment

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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:

```bash
# 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

```bash
# 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

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

    # Act
    result = call_feature()

    # Assert
    assert result.is_valid()
```

### Running Tests

```bash
# 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

```python
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

```bash
# Build containers
make docker-build

# Run development environment
make docker-dev

# Run production environment
make docker-prod

# Clean up
make docker-clean
```

### Container Registry

```bash
# Build and push to registry
make registry-push

# Login to registry
make docker-login
```

## 🔧 Debugging

### Common Issues

**Import Errors:**
```bash
# Ensure you're in the virtual environment
source .venv/bin/activate

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

**Test Failures:**
```bash
# Run tests with verbose output
make test -v

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

**Linting Errors:**
```bash
# Auto-fix formatting issues
make format

# Check what lint issues remain
make lint
```

### Development Tools

```bash
# 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.*