Welcome! We're glad you're here.
# 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 syncVS Code: Command Palette → "Python: Select Interpreter" → enter .venv/bin/python
PyCharm: Settings → Python Interpreter → Add Interpreter → type uv, point to .venv/bin/python. Details
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 issuesRun just by itself to see all available recipes.
git commit -am "<type>(<scope>): <description>"
git push -u origin your-branch-name
gh pr create --fill --repo feldroy/airFor commit message format, see the Conventional Commits Cheatsheet.
Important
Fill out the Pull Request Template completely. It helps maintainers review your contribution quickly.
- 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.
Important
Have an idea for a new feature? Open an issue to discuss it before writing code. We want to keep Air light and breezy.
| 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.
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:(orYields:), andExample:directives - HTML tags in docstrings must be in backticks (
`<tag>`) or code blocks
- Delete
.venv/and runuv venvto 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-runuv sync - Upgrade uv:
uv self update - Still stuck? File a GitHub issue with details
- Bump the version and write the changelog:
Then write
uv version <version> # or: uv version --bump minor
CHANGELOG/<version>.md. See previous entries for the format. - Commit:
git add pyproject.toml uv.lock CHANGELOG/ git commit -m "Release <version>" - Release:
This creates an annotated
just release
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.
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.