Development Workflow

This page describes the day-to-day workflow for contributing to Buffalo Wings after your development environment is already set up. If you still need to set up the repository, start with Getting Started Developing.

Goal

Use this page when you are actively making changes in the repository. It focuses on the normal contributor loop: make a focused change, run the relevant checks, update docs and examples when needed, and prepare the branch for review.

1. Typical Development Loop

A normal development cycle looks like this:

  1. Create or update a working branch.

  2. Make a focused code or documentation change.

  3. Run the smallest useful test or check for the change.

  4. Update tests, docs, or examples if public behavior changed.

  5. Run the broader project checks before finishing.

  6. Review the diff and open or update a pull request.

2. Create Or Update A Branch

Start from an up-to-date main branch:

git checkout main
git pull --ff-only
git checkout -b feature/short-description

If you are continuing existing work, switch to the branch and pull any needed updates before editing.

3. Make Focused Changes

Keep each change set as small and intentional as practical.

Good practice includes:

  • avoid unrelated reformatting,

  • avoid mixing refactors with behavior changes unless they must happen together,

  • keep public API changes separate from internal cleanup when possible,

  • and review edited files before committing to catch accidental churn.

4. Run The Smallest Useful Checks First

Use targeted checks while developing so feedback stays fast.

Run a focused test file:

uv run pytest tests/path/to/test_file.py

Run tests matching a keyword:

uv run pytest -k "keyword"

Run Ruff on the repository:

uv run ruff check .
uv run ruff format . --check

Run the strict type checkers:

uv run mypy
uv run basedpyright

If you are working on examples, run the example directly with:

uv run python examples/<path-to-example>.py

5. Run The Full Project Checks

Before finishing substantial work, run the standard full check script:

./scripts/run_checks.sh

On Windows, use:

scripts\run_checks.bat

This is the main local CI-parity check and should pass before you consider the work complete.

6. Build The Documentation When Needed

If you changed docs, examples shown in the docs, or public APIs that affect documentation, rebuild the docs:

./scripts/build_docs.sh

On Windows, use:

scripts\build_docs.bat

This also refreshes the generated example output files used by the Sphinx examples page.

7. Public API And Import Policy

User-facing code should use the supported public modules:

  • buffalo_wings.airfoil as bwa

  • buffalo_wings.wing as bww

  • buffalo_wings.type_aliases as bw_type

Prefer these public imports in:

  • examples,

  • documentation snippets,

  • and tests that validate the supported external API.

Imports from buffalo_wings.*.internal should be limited to implementation code and tests that are explicitly about internal behavior.

8. Update Tests, Docs, And Examples With Behavior Changes

When behavior changes, make sure the supporting materials change with it.

In general:

  • changed behavior should have updated or new tests,

  • public API changes should update documentation,

  • public API changes should update or add an example under examples/,

  • and documentation examples should have refreshed generated output if they are shown in Sphinx.

For the example-specific workflow, see Example Workflow.

9. Review Before Opening A PR

Before opening or updating a pull request, check the following:

  • the diff is focused,

  • tests and checks pass,

  • docs were rebuilt if needed,

  • generated example outputs were refreshed if needed,

  • and commit messages are clear.

For the repository contribution process, see Contributing.