iron/CONTRIBUTING.md

Contributing

Thanks for helping improve Iron. The project is still early, so the most useful contributions are focused changes with tests and clear documentation updates.

Development Setup

UV_CACHE_DIR=.uv-cache uv venv .venv
UV_CACHE_DIR=.uv-cache uv pip install --python .venv/bin/python -e '.[dev]'
npm install
npm run build

Run the API locally:

.venv/bin/python -m uvicorn app.main:app --reload

Open http://127.0.0.1:8000/app.

Test Before Submitting

Run the full suite:

.venv/bin/python -m pytest

For UI changes, also run:

npm run build
.venv/bin/python scripts/ui_playwright_smoke.py

Review screenshots in output/playwright/ before considering UI work complete.

Pull Request Checklist

• The change is focused and described clearly.
• Tests were added or updated for behavior changes.
• UI changes were validated with Playwright when applicable.
• Documentation was updated if setup, behavior, or architecture changed.
• Generated/runtime files are not included.

Code Style

• Backend code lives in app/ and uses async FastAPI + SQLAlchemy patterns.
• Frontend code lives in frontend/ and uses React, React Router, and TanStack Query.
• Keep browser file preview/download flows authenticated through the API client.
• Prefer clear names and small modules over clever abstractions.

Project Status

Iron is a Product MVP Candidate. See:

• docs/product.md
• docs/architecture.md
• docs/development.md