Skip to content

README.md

Latest commit

 

History

History
202 lines (141 loc) · 9.22 KB

README.md

File metadata and controls

202 lines (141 loc) · 9.22 KB
Raw

Documentation

This directory contains project documentation and architectural decision records (ADRs).

Documentation Organization

Directory Structure and Standards

  • user-guide/ - User-facing documentation (installation, usage, tutorials, troubleshooting)
  • dev-journal/ - Development journal and historical analysis documents with date-stamped filenames (YYYYMMDD-topic.md)
  • adrs/ - Architecture Decision Records (ADRs) documenting significant architectural decisions
  • Root docs/ - Single-file documentation (this README.md file, standards)
  • Additional subdirectories - Topic-specific multi-file documentation as needed

Architecture Decision Records (ADRs)

ADRs document significant architectural decisions made during development, providing context for why certain choices were made. Each ADR captures:

  • Context: The situation that led to the decision
  • Decision: The architectural choice that was made
  • Consequences: The positive and negative outcomes
  • Alternatives: Other options that were considered

We follow the Michael Nygard ADR template.

Current ADRs

Project Structure and Scope

Testing Architecture

Implementation Patterns

Related Analysis Documents

Creating New ADRs

When making significant architectural decisions:

  1. Create a new ADR file in adrs/ with format: NNNN-decision-title.md (e.g., 0003-caching-strategy.md)
  2. Follow the Michael Nygard template
  3. Update this README.md file to list the new ADR in the "Current ADRs" section
  4. Reference the ADR in relevant code or documentation
  5. Consider adding detailed analysis to dev-journal/ if needed (link from ADR)

Development Standards

This project adheres to several development standards to ensure consistency, maintainability, and quality.

Semantic Versioning

This project follows Semantic Versioning (SemVer) for version numbering:

  • MAJOR.MINOR.PATCH format (e.g., 1.2.3)
  • MAJOR: Incompatible API changes
  • MINOR: New functionality in a backward-compatible manner
  • PATCH: Backward-compatible bug fixes

Conventional Commits

This project follows the Conventional Commits specification for commit message formatting. This standard provides a structured format for commit messages that enables automated tools for generating changelogs, determining semantic versioning, and more.

Commit Message Format

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

Types

  • feat: A new feature
  • fix: A bug fix
  • docs: Documentation only changes
  • style: Changes that do not affect the meaning of the code (white-space, formatting, etc)
  • refactor: A code change that neither fixes a bug nor adds a feature
  • perf: A code change that improves performance
  • test: Adding missing tests or correcting existing tests
  • chore: Changes to the build process or auxiliary tools and libraries

Examples

feat: add vm_create operation for OrbStack VMs
fix(connector): handle SSH connection failures gracefully
docs: update installation instructions for uv package manager
refactor(operations): simplify VM status checking logic
test: add unit tests for OrbStackConnector class
chore: update dependencies to latest versions

Benefits

  • Automated Changelog Generation: Commit messages can be parsed to automatically generate changelogs
  • Semantic Versioning: Commit types help determine version bumps (feat = minor, fix = patch, breaking = major)
  • Clear History: Structured messages make it easier to understand project history
  • Tool Integration: Works with tools like semantic-release, conventional-changelog, and more

Keep a Changelog

This project follows the Keep a Changelog format for the CHANGELOG.md file:

  • Unreleased: Changes that haven't been released yet
  • Versioned sections: Each release has its own section
  • Categorized changes: Added, Changed, Deprecated, Removed, Fixed, Security
  • Chronological order: Most recent changes first

Development Workflow

Running Tests

# Install development dependencies
uv sync --dev

# Run tests
uv run pytest

# Run with coverage
uv run pytest --cov=src/pyinfra_orbstack

# Alternative using pip
pip install -e ".[dev]"
pytest
pytest --cov=src/pyinfra_orbstack

Code Quality

# Format code
uv run black src/ tests/

# Lint code
uv run flake8 src/ tests/

# Type checking
uv run mypy src/

# Alternative using pip
black src/ tests/
flake8 src/ tests/
mypy src/

Pre-commit Hooks

This project uses pre-commit hooks to ensure code quality:

# Install pre-commit hooks
uv run pre-commit install

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

Testing Documentation

System Performance and Troubleshooting

References