Skip to content

Development Guide

Auto-generated by BMAD Document Project workflow on 2026-02-28. Scan level: exhaustive

Prerequisites

Requirement Version Notes
Python 3.12 Strictly required (>=3.12,<3.13)
uv Latest Package manager + build tool
Git Any Version control
pre-commit Any Optional but recommended for hooks

Setup

# Clone and checkout main branch
git clone https://github.com/Alberto-Codes/adk-secure-sessions.git
cd adk-secure-sessions
git checkout main

# Install all dependencies (runtime + dev)
uv sync --dev

# Verify setup
uv run pytest           # Run tests
uv run ruff check .     # Lint check

Common Commands

Command Purpose
uv run pytest Run all tests
uv run pytest -m unit Run unit tests only
uv run pytest -m integration Run integration tests only
uv run pytest --cov=adk_secure_sessions --cov-report=term-missing Tests with coverage
uv run ruff check . Lint check
uv run ruff check . --fix Auto-fix lint issues
uv run ruff format . Format code
uv run ruff format --check . Check formatting without changes
uv run ty check src/ Type checking
uv run docvet check --all Docstring quality
uv run uv-secure Dependency vulnerability scan
pre-commit run --all-files Full quality pipeline (lint, format, ty, tests, docvet)
uv run mkdocs serve Local docs preview
uv run mkdocs build Build docs site

Pre-Commit Hooks

Seven hooks run on each commit:

Hook What it checks
yamllint YAML syntax and formatting
actionlint GitHub Actions workflow validity
ruff-check Python linting
ruff-format Python code formatting
ty Type checking (src/ only)
pytest Full test suite
docvet Docstring quality on staged files

Install with: pre-commit install

CI/CD Pipelines

Tests Workflow (.github/workflows/tests.yml)

  • Trigger: Push to main, PRs to main
  • Matrix: Python 3.12 x ADK versions (1.22.0, latest)
  • Steps: Lint, format check, type check, tests with 90% coverage minimum

Docs Workflow (.github/workflows/docs.yml)

  • Trigger: PRs modifying docs/, src/**/*.py, mkdocs.yml, pyproject.toml
  • Steps: Build MkDocs site to verify no broken builds

Release Please (.github/workflows/release-please.yml)

  • Trigger: Push to main
  • Steps: Automated release PR creation via release-please

Code Style

  • Guide: Google Python Style Guide
  • Docstrings: Google-style with Examples sections
  • Line length: 88 (formatter), 100 (linter threshold)
  • Quotes: Double quotes
  • Imports: Sorted by ruff/isort (stdlib, third-party, local)
  • Type hints: Required on all public functions, modern syntax (list[str], X | None)
  • Async: All public APIs are async def; CPU-bound work wrapped in asyncio.to_thread()

Branch Workflow

  • Base branch: main
  • Branch naming: feat/, fix/, docs/, refactor/, test/
  • Commit style: Conventional commits (type(scope): description)
  • PRs: Always draft (--draft), target main, follow PR template

SonarQube Integration

  • Project key: adk-secure-sessions
  • Server: Local LAN SonarQube Community Edition
  • Scanner: Podman-based sonar-scanner-cli
  • Key metric: Cognitive complexity threshold 15 (target 12 for buffer)
  • Scans: Manual only (Community Edition, no branch analysis)

Testing Conventions

  • Framework: pytest + pytest-asyncio (auto mode)
  • Mocking: pytest-mock (mocker fixture), never unittest.mock
  • Markers: @pytest.mark.unit, @pytest.mark.integration
  • Fixtures: Async generators with proper teardown (yield svc; await svc.close())
  • Warnings: Treated as errors; third-party warnings filtered in pyproject.toml