Skip to content

Maintenance Guide

Dependency Updates

  • Vulnerability scanning: pip-audit runs in CI (.github/workflows/) on every push. Failures block the build.
  • Outdated dependencies: Review with pip list --outdated before each release. Pin upper bounds in pyproject.toml only when known incompatibilities exist.
  • Lockfile: uv.lock is committed. Regenerate with uv lock after changing pyproject.toml.
  • Pre-commit hooks: Defined in .pre-commit-config.yaml. Run pre-commit autoupdate monthly.

Security Patching

  • SAST: bandit runs in CI (tool.bandit config in pyproject.toml excludes tests/, .venv, .tox; skips B101 — assert allowed in non-test code).
  • Critical CVEs: Trigger an immediate patch release. Process:
  • Fix in a branch
  • Add regression test in tests/test_security*.py or relevant test file
  • Run lint.sh && test.sh (or make lint test)
  • Tag v{patch}.{minor}.{patch+1}
  • Update CHANGELOG.md under ### Security
  • Secrets: No credentials, tokens, or private keys are committed. The .env file is gitignored. Configuration.to_dict() redacts every secret-shaped field across every config section.

Technical Debt Management

Tracked in docs/REFACTORING_PLAN.md and docs/ROADMAP.md. v0.9 hardening landed; remaining v1.0 deferrals are itemised in the Roadmap.

Before each release, run ruff check underwrite/ tests/ and mypy underwrite/ tests/ to prevent regression. Current ruff config: select = ["E", "F", "I", "UP", "B"], line length 120. mypy runs against both underwrite/ and tests/ with strict typing — no ignore_errors safety net.

Test Maintenance

  • Pre-release: Run pytest tests/ -q (1276 tests as of v0.9). All tests must pass.
  • Coverage: Run pytest --cov=underwrite tests/ — keep coverage ≥ 80% (gate enforced in CI).
  • Regression tests: Every bug fix must include a test that fails before the fix and passes after.
  • Mutation testing: mutmut run (config in pyproject.toml: paths ["underwrite"], runner python -m pytest tests/ -x --timeout=30). Run before major releases.
  • Stress/concurrency tests: 30+ concurrency stress tests already in tests/test_concurrency.py, tests/test_concurrency_faults.py, and the per-service fault-injection suites. Add more as needed.

Documentation Maintenance

  • docs/: Update when adding new features, services, event types, or configuration options.
  • mkdocs.yml: Keep the nav section consistent with the docs/ directory structure. Currently only 4 entries in nav — expand as files are added.
  • README.md: Keep the description, quickstart, and badge list current.
  • CHANGELOG.md: Every release gets an entry under ## [version] with ### Added, ### Changed, ### Fixed, ### Security sections.

Deprecation Policy

  1. Mark deprecated APIs with a .. deprecated:: directive in the docstring and add a warnings.warn(..., DeprecationWarning) call.
  2. Keep the deprecated API for 2 minor versions (e.g. deprecated in v0.4.0, removed in v0.6.0).
  3. Document the removal in CHANGELOG.md under ### Changed with a migration note.

Upgrade Paths

  • Breaking changes are documented in CHANGELOG.md with a ### Changed entry describing the migration.
  • The version.py file is auto-generated by setuptools-scm from git tags — always tag releases.
  • For database schema changes, use MigrationPlan in migrate.py and test with test_migrate.py.