Skip to content

Development Standards.md

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

Development Standards

This page covers branching conventions, PR requirements, and coding standards — both what is codified in the repo and what is implied by the codebase.

Branching Strategy

The Jira automation workflow generates branches as jira/<JIRA_KEY>-<slug>. For work outside Jira-driven automation, the following conventions are recommended:

Branch Type Pattern Example
Jira-driven jira/<KEY>-<slug> jira/OCO-42-add-sensor-endpoint
New feature feature/<name> feature/bulk-chemistry-import
Bug fix bugfix/<issue> bugfix/null-location-geometry
Hotfix hotfix/<issue> hotfix/auth-bypass-in-prod
Refactor refactor/<component> refactor/water-level-service

Needs confirmation: Whether the team expects all human-created branches to follow the Jira pattern, or only automation-created ones. No formal branch naming policy document currently exists in the repo.

Pull Request Requirements

Passing CI

GitHub Actions must pass before merging:

  • Tests (unit, integration, BDD)
  • Formatting (black)
  • Linting (flake8)

Pre-merge checklist

  • black run on all touched Python files
  • flake8 run on all touched Python files
  • Targeted tests pass for the changed area
  • Broader validation run if the change affects DB boot, migrations, deploy, or shared runtime setup
  • Migration and test updates included when behavior or schema changes

Schema and migration changes

Any new model or field change must include an Alembic migration. Run alembic revision --autogenerate -m "description", then review the generated output before committing — autogenerate can miss spatial or custom column types.

Documentation

Update relevant wiki pages when any of the following change: local setup steps, environment variables, migrations, transfer pipeline behavior, deployment steps, or OGC API collections (core/pygeoapi-config.yml). Add docstrings for complex business logic in services/.

Needs confirmation: Required reviewers, minimum approvals, and whether PR descriptions must follow any internal format. No PR template or CODEOWNERS file currently exists in the repo.

Coding Standards

Exception handling

Never use standard HTTPException. Use PydanticStyleException for consistency:

from services.exceptions_helper import PydanticStyleException

raise PydanticStyleException(
    status_code=409,
    detail=[{
        "loc": ["body", "location_name"],
        "msg": "Location already exists.",
        "type": "duplicate_value"
    }]
)

Schema conventions

Schema Type Field Nullability
Create* Required as <type>, optional as <type> | None = None
Update* All fields optional with None default
*Response Explicitly define all return types

Database model conventions

  • Inherit from Base and include AutoBaseMixin
  • Use ReleaseMixin for entities that require visibility control
  • Use DataProvenanceMixin for tracking data source methods

Architecture conventions

  • Keep routers focused on request/response concerns only
  • Put reusable business logic in services/
  • Keep CLI commands thin; push heavy work into services or transfer modules
  • For high-volume transfer tables, prefer SQLAlchemy Core batch inserts over ORM object construction

Formatting and linting

Tool Scope
black Auto-formatting (enforced by pre-commit and CI)
flake8 Linting focused on serious syntax/import/runtime categories
pre-commit Runs both on commit; CI auto-commits formatting fixes on non-environment branches

Recommended Next Improvement

Add a CONTRIBUTING.md or PR template to the repo so branch naming, review expectations, and migration/testing requirements are codified in one place rather than inferred from workflows and this wiki.

Clone this wiki locally