Development Guide

Development Guide

Set up a local development environment for simple-resume.

First, fork and clone the repository. This project uses uv for dependency management. To install all development and optional dependencies, run the following command:

uv sync --dev --extra utils

Running Code Quality Checks

The Makefile includes commands for common development tasks.

Running Tests

To run the full test suite, including unit and integration tests:

make test

Linting and Formatting

ruff handles linting and code formatting. To run all checks (linting, formatting, type-checking, security scans):

make check-all
make validate  # Runs secondary validation, like checking the README preview and release assets.

Individual checks can also be run:

# Run the linter
make lint

# Format the code
make format

Architecture

The project uses a functional core, imperative shell pattern to separate pure data transformations from code that produces side effects.

• Functional Core (src/simple_resume/core/): Contains pure functions for data manipulation. These functions are predictable and do not have side effects, which makes them easy to test.
• Imperative Shell (src/simple_resume/shell/): Manages I/O, user interaction, and integrations with external services. Side effects are handled in this layer.
• API Surface (src/simple_resume/): The public API provides an interface for reading and writing resume data (e.g., read_yaml(), to_pdf()).

Key Components

• Resume class: The main entry point for the public API. It provides methods such as read_yaml(), to_pdf(), and to_html().
• ResumeSession: A class that manages configuration settings for consistency across multiple operations.
• Palette System: A system for color management that supports built-in themes, remote palettes, and generated color schemes.
• Template System: Uses Jinja2 for HTML and LaTeX templating.
• Validation: A validation layer that provides error messages for configuration and data issues.

Testing

The project maintains over 85% test coverage with unit and integration tests.

# Run all tests
make test

# Run specific test categories
make test-unit
make test-integration

# Run tests with coverage
make test-coverage

Documentation

Our documentation is organized into these key areas:

• Architecture Decisions (ADRs): Records the history and reasoning behind significant technical decisions.
• Usage Guide: Explains how to use the library's features with practical examples.
• Migration Guide: Provides instructions for upgrading between major versions.
• Lazy Loading Guide: Describes performance optimization strategies.
• API Reference: A reference for the public API.

When contributing to the documentation, please adhere to the following best practices:

• Write clearly and concisely.
• Add code examples for all major features.
• Document both lazy and eager loading approaches.
• Explain performance trade-offs.
• Provide migration paths for breaking changes.
• Update ADRs for significant architectural changes.
• Keep docstrings current.

Contributing

Please read the Contributing Guide for information on the development process, coding standards, and how to submit pull requests.

Development Workflow

1. Create a feature branch from main.
2. Make your changes and add tests.
3. Run make check-all and make validate to verify that all automated checks pass.
4. Submit a pull request with a clear description of your changes.