Getting Started Developing

This page is for contributors who want to work on Buffalo Wings itself. If you want to use the library, start with the examples page and the public API reference instead.

1. Prerequisites

Buffalo Wings targets Python 3.12. Development commands in this repository use uv to manage environments and run tools.

Before starting, make sure you have:

  • Python 3.12

  • uv

  • git

2. Clone And Set Up The Repository

Clone the repository and create the project environment:

git clone https://codeberg.org/BuffaloHerd/BuffaloWings.git
cd BuffaloWings
uv sync --locked

This installs the pinned development dependencies used by the project.

3. Run The Standard Checks

Run the full local checks from the repository root:

./scripts/run_checks.sh

On Windows, use:

scripts\run_checks.bat

These checks run the project’s standard quality gates, including tests, linting, type checking, and documentation-related checks.

4. Build The Documentation

Build the Sphinx documentation with:

./scripts/build_docs.sh

On Windows, use:

scripts\build_docs.bat

The built HTML documentation will be written to sphinx/build/html.

5. Daily Development Commands

Common commands during day-to-day development are:

uv run pytest
uv run ruff check .
uv run ruff format . --check
uv run mypy
uv run basedpyright

Run a focused test file with:

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

6. Repository Layout

The main repository layout is:

  • src/ for library code

  • tests/ for automated tests

  • examples/ for user-facing example scripts

  • docs/ for design notes, specifications, and workflow documentation

  • sphinx/ for the documentation build inputs and generated site structure

  • scripts/ for repository automation such as checks and docs builds

Public package interfaces are exposed from package __init__.py files. Concrete implementations generally live under internal/ subpackages.

7. Development Expectations

When making changes:

  • keep changes focused and avoid unrelated reformatting,

  • add or update tests for changed behavior,

  • update documentation when public behavior changes,

  • update an example under examples/ when the public API changes,

  • keep the public API under buffalo_wings.airfoil and buffalo_wings.wing,

  • treat modules under buffalo_wings.*.internal as implementation details.

The supported external modules are buffalo_wings.airfoil, buffalo_wings.wing, and buffalo_wings.type_aliases. Examples, documentation snippets, and public API tests should generally import these modules as bwa, bww, and bw_type. Direct imports from internal/ should be limited to library implementation code and tests that explicitly validate internal behavior.

8. Where To Go Next

After your environment is working, the most useful detailed workflow pages are:

For project architecture and source-of-truth design information, start with the numeric typing guide, the wing design document, the Python package layout guide, and the roadmap.