Skip to content

Contributing

Thanks for helping make U.S. public data easier to use. Setup and commands are in README.md; this file covers the workflow and conventions.

Workflow

  1. Open or pick an issue. Dataset requests use the "Dataset request" template.
  2. Branch from main with a type prefix: feat/, fix/, docs/, refactor/, chore/.
  3. Make the change. Add or update tests. Run just check.
  4. Add a release-note fragment; use internal with a reason when there is no user-facing change.
  5. Open a pull request. The template has the checklist. CI must pass; main only accepts squash merges, so the PR title becomes the commit message and should be a Conventional Commit: feat: add usgs:nwis-daily adapter. CI validates this title, including edits.

Fast commit hooks are optional; see setup. CI runs the same configuration and workflow checks even when hooks are not installed. Dependabot proposes weekly updates to the SHA-pinned GitHub Actions. To refresh hook revisions, run uv run pre-commit autoupdate and review them in a PR.

After merging

Return to the main checkout (git switch main when working in the primary checkout), then run just cleanup PR_NUMBER. Cleanup verifies that the PR merged into main and that the local branch still matches its exact head. It removes a clean associated topic worktree and the local branch, then leaves main current. It refuses dirty worktrees, changed branch tips, and fork PRs. Ignored lockfiles, downloads, and notebook reports must be preserved elsewhere first; only known regenerable tool/build caches are disposable. GitHub deletes the remote branch after merge. Keep any branch with additional work for a separate PR.

Adding a dataset

This is the main way the project grows. The full walkthrough is in docs/guides/adding-a-dataset.md. In short:

  • one entry in src/usdata/data/registry.yaml,
  • one Provider subclass under src/usdata/providers/<agency>/,
  • adapter tests with mocked HTTP under tests/adapters/,
  • one live test under tests/live/ marked live.

Conventions

  • Python 3.11+. Formatting and linting by ruff, types by pyright, both enforced in CI.
  • Core runtime dependencies stay at pydantic, pyyaml, typer, httpx. Anything heavier goes behind an optional extra.
  • Offline tests never touch the network. Live tests are marked live and run weekly, not on PRs.
  • Bundled data files under src/usdata/data/ are generated by scripts in scripts/. Regenerate rather than hand-edit.
  • Design decisions that get argued about become an ADR in docs/adr/.
  • Commit messages have no Co-Authored-By trailers.

Definition of done

  • Acceptance criteria in the issue are met.
  • Tests added or updated; just check passes.
  • Docs updated: README, guides, registry entry, or ADR as appropriate.
  • Release-note fragment added; generated changelog history is not edited by hand.
  • Security implications considered (see SECURITY.md).

For documentation changes, see maintaining the docs.