Contributing to envresolve¶

Thank you for considering contributing to envresolve!

Development Setup¶

Prerequisites¶

Python 3.10 or higher
uv package manager
Git

Setup¶

Fork the repository on GitHub.
Clone your fork locally:

git clone https://github.com/YOUR-USERNAME/envresolve.git
cd envresolve

Add the upstream remote to sync with the main repository:

git remote add upstream https://github.com/osoekawaitlab/envresolve.git

Install dependencies:

uv sync

Run tests to verify setup:

nox -s tests

Development Workflow¶

envresolve follows a strict Test-Driven Development (TDD) cycle.

Running Tests¶

# All tests with coverage
nox -s tests

# Unit tests only
nox -s tests_unit

# E2E tests only
nox -s tests_e2e

# All Python versions
nox -s tests_all_versions

Code Quality¶

# Type checking
nox -s mypy

# Linting
nox -s lint

# Format code
nox -s format_code

# All quality checks
nox -s quality

# Everything (tests + quality)
nox -s check_all

Code Style¶

Type Hints: Required for all public APIs
Docstrings: Google style, required for all public functions/classes
Linting: Ruff with "ALL" rules (see pyproject.toml)
Type Checking: Strict mypy configuration

Pull Request Process¶

Create a new branch from main
Make your changes following the TDD cycle
Ensure all tests pass: nox -s check_all
Update documentation if needed
Write or update ADRs for architectural decisions
Submit a pull request with a clear description

PR Checklist¶

[ ] Tests added/updated and passing
[ ] Code follows style guidelines (ruff check passes)
[ ] Type hints added (mypy passes)
[ ] Docstrings added/updated (Google style)
[ ] Coverage maintained at 80%+
[ ] ADRs written for design decisions
[ ] Documentation updated if needed

Architecture¶

envresolve follows a layered architecture:

Layer 5: api.py (Public API facade)
Layer 4: application/ (resolver, cache)
Layer 3: providers/ (factory, registry, implementations)
Layer 2: services/ (reference, expansion)
Layer 1: Domain (models, exceptions) + Infrastructure (base, logging)
Layer 0: External dependencies

Key Principles:

Higher layers depend on lower layers
Lower layers NEVER depend on higher layers
Domain layer has NO internal dependencies

See Architecture ADRs for design decisions.

Documentation¶

Documentation is built with MkDocs Material:

# Serve documentation locally
mkdocs serve

# Build documentation
mkdocs build

Documentation Structure¶

User Guide: Installation and usage tutorials
API Reference: Auto-generated from docstrings (mkdocstrings)
Architecture: ADRs and design decisions
Contributing: This file

Reporting Issues¶

Use the GitHub issue tracker to report bugs or request features.

When reporting bugs, please include:

Python version
envresolve version
Minimal code to reproduce
Expected vs actual behavior
Error messages/stack traces

Questions?¶

Check the documentation
Review existing issues
Open a new issue for questions

License¶

By contributing, you agree that your contributions will be licensed under the MIT License.

Live Azure Tests¶

Optional integration tests against real Azure Key Vault infrastructure. Run these tests to validate changes that affect Azure SDK integration or provider implementations.

Note: Live tests automatically skip when environment variables are not set (ENVRESOLVE_LIVE_KEY_VAULT_NAME, etc.), so they won't interfere with normal development.

One-Time Setup¶

# 1. Configure terraform (requires Azure subscription and az login)
cd infra/terraform
cp terraform.tfvars.example terraform.tfvars

# 2. Edit terraform.tfvars with your values:
#    - subscription_id, tenant_id, name_prefix
#    - test_principal_object_id (get your object ID: az ad signed-in-user show --query id -o tsv)

# 3. Create resources
terraform init
terraform apply

# 4. Return to project root and set environment variables (per shell session)
cd ../..
source scripts/setup_live_tests.sh

Running Live Tests¶

nox -s tests_live

Cleanup¶

Resources can be kept for reuse. Destroy only when done:

cd infra/terraform
terraform destroy