Contributing to the Air Web Framework

Welcome! We're glad you're here.

Prerequisites

1. uv (package manager)
2. just (command runner)
3. gh (GitHub CLI)

Getting started

# Fork, clone, and set up remotes in one step
gh repo fork feldroy/air --clone --remote
cd air

# Fetch latest and create your branch
git fetch upstream
git switch -c your-branch-name upstream/main

# Install dependencies
just sync

IDE setup

VS Code: Command Palette → "Python: Select Interpreter" → enter .venv/bin/python

PyCharm: Settings → Python Interpreter → Add Interpreter → type uv, point to .venv/bin/python. Details

Development workflow

Make your changes, then:

just qa      # format check + lint + type check (must pass before PR)
just test    # run the test suite (must pass before PR)
just fix     # auto-fix formatting and lint issues

Run just by itself to see all available recipes.

Submitting your PR

git commit -am "<type>(<scope>): <description>"
git push -u origin your-branch-name
gh pr create --fill --repo feldroy/air

For commit message format, see the Conventional Commits Cheatsheet.

What we're looking for

• Bug fixes: Found a bug? Submit a PR with a fix.
• Refactoring: Improvements for clarity, performance, and maintainability.
• Documentation: Better docstrings and docs are always appreciated.
• Features: Any feature ticket marked with Status: Approved.

Feature categories

Category	Label
Core Air Feature	Feature: Core
Optional Air Feature	Feature: Optional
Third-Party Integrated Feature	Feature: Third-Party Integrated
Out-of-Scope Feature	Feature: Out-of-Scope

Core: In the main repo, on by default. Fully documented and tested. Examples: Air Tags, FastAPI integration controls.

Optional: In the repo but off by default, installed via extras. Opt-in to keep the core small. Examples: authentication, CSRF validation.

Third-Party Integrated: Not implemented by Air. We provide guides and examples for integrating external libraries. Example: SQL integration.

Out-of-Scope: Not implemented, documented, or supported. Redirected to community solutions.

Docstrings and API reference

The API reference is generated from docstrings in this repo and built with MkDocs (see mkdocs.yaml and docs/). Rules:

• Every public function, class, and method needs a docstring
• Every new public callable must include at least one working example
• Use Google style docstrings in Markdown format
• Use Args:, Return: (or Yields:), and Example: directives
• HTML tags in docstrings must be in backticks (`<tag>`) or code blocks

Troubleshooting

• Delete .venv/ and run uv venv to recreate the virtualenv
• Make sure you're not activating another virtualenv in your shell startup files
• If code changes don't apply, use uv run <command> (auto-syncs) or re-run uv sync
• Upgrade uv: uv self update
• Still stuck? File a GitHub issue with details

Releasing a New Version

1. Bump the version and write the changelog:

   uv version <version>        # or: uv version --bump minor
   

   Then write CHANGELOG/<version>.md. See previous entries for the format.
2. Commit:

   git add pyproject.toml uv.lock CHANGELOG/
   git commit -m "Release <version>"
   

3. Release:

   just release
   

   This creates an annotated v* tag, pushes it to GitHub, and creates a GitHub Release with the changelog contents as release notes. The tag push triggers .github/workflows/publish.yml, which builds the package, generates SLSA provenance attestations, and publishes to PyPI via trusted publishing.

Code of Conduct

Please note that this project is released with a Contributor Code of Conduct. By participating in this project you agree to abide by its terms.