Skip to content

Development Workflow.md

Jump to bottom
Kelsey Smuczynski edited this page Mar 24, 2026 · 1 revision

Development Workflow

Standard Local Workflow

source .venv/bin/activate
set -a; source .env; set +a
alembic upgrade head
uvicorn main:app --reload

For containerized development:

docker compose up --build

Iterative Feature Development

The recommended loop for new features:

  1. Create a branch (see Development Standards for naming)
  2. Add a test in tests/ that describes the expected behavior
  3. Implement the feature
  4. Run uv run pytest
  5. Run pre-commit run --all-files to fix formatting

When Changing Models

  1. Update SQLAlchemy models in db/
  2. Update Pydantic schemas in schemas/
  3. Generate migration: alembic revision --autogenerate -m "description"
  4. Review the generated migration script for accuracy
  5. Apply: alembic upgrade head
  6. Update tests and fixtures
  7. Update transfer logic if the field participates in legacy migration

Always review autogenerated migration scripts before applying — they can miss spatial or custom column types.

When Changing Business Logic

  • Keep routers focused on transport concerns (request/response)
  • Put reusable logic in services/
  • Keep CLI commands thin; push heavy work into services or transfer modules

Data Migration Workflow

The repo has a formal post-Alembic data migration layer for corrective or transitional data changes:

python -m cli.cli data-migrations list
python -m cli.cli data-migrations status
python -m cli.cli data-migrations run <migration_id>
python -m cli.cli alembic-upgrade-and-data   # runs both Alembic + data migrations

These migrations are tracked in data_migration_history and gated by applied Alembic revisions. Keep them idempotent and safe to re-run.

Project-Area Boundary Import

There is a dedicated CLI command for ArcGIS project area boundaries:

python -m cli.cli import-project-area-boundaries

By default, it reads from a New Mexico Tech ArcGIS Feature Layer URL.

GitHub Workflow Signals

Trigger Action
PR targeting production, staging, or transfer Runs full test suite
Push to staging Deploys staging
Push to production Deploys production
Push to main Creates a Sentry release

Known Drift

README.md still contains an outdated project structure snippet and an outdated uvicorn command. Prefer the code and this wiki over those sections until the README is updated.

Clone this wiki locally