# Contributing to Ollin

Ollin is alpha and pre-1.0, and it is built on nights and weekends. Contributions and ideas are welcome. This page collects the practical details, and the README's [Status & contributing](about.md#status-contributing) section sets the expectations.

## Where to start

- [`ROADMAP.md`](roadmap.md) is the best place to find work. Its [Up next](roadmap.md#up-next) section lists items that fit small, self-contained pull requests.
- Check [`CAPABILITIES.md`](capabilities.md) before you assume a capability is missing. It has one bullet per shipped capability, with pointers to its example, tests, and docs.
- [`ARCHITECTURE.md`](architecture.md) explains how the larger systems work inside. [`DESIGN-NOTES.md`](design-notes.md) covers the intent behind the work that is still planned.

## Before a large change

Open an issue first and talk the change through. A small, self-contained fix or addition can go straight to a pull request.

## Working on the code

You need macOS 26+ with a Metal-capable GPU and a Swift 6 toolchain.

- Run an example to see the framework working: `swift run --package-path Examples Example-Basic-HelloCircle`.
- Run the tests for the area you touched with `Scripts/test.sh <Suite>`. `Scripts/test.sh quick` runs the pass that takes under a minute, and the full suite takes many minutes.
- Run `Scripts/preflight.sh` before every commit. It reads your diff and runs every gate that applies and nothing else (tests, link checks, prose lint). It also says what it skipped and why.
- A change to the public API fails preflight until you run `Scripts/api-surface.sh --record` and commit the rewritten listing under `API/` with it. That diff is how a reviewer sees what the surface gained, lost, or renamed; the changelog names a rename by both names. `Scripts/api-diff.sh` reads that listing against the last tag and says what the change means for the next version; `--changelog` prints the skeleton of the entry. `Scripts/check-api-pages.sh` reads the same listing the other way and fails when a public name is named by no page under `Docs/`, so a new name arrives with somewhere to read about it.
- A new capability ships with an example, a test, and a `Docs/` page. The full ship checklist is in `CLAUDE.md`.
- A change a user would notice gets a line under *Unreleased* in [`CHANGELOG.md`](changelog.md). A rename names both the old and the new spelling in that line.
- `Scripts/release-smoke.sh` builds Ollin the way somebody who only has a tag does: it generates the project `ollin new --remote` writes, lets SwiftPM fetch the framework from GitHub at a published tag, builds it, and renders one frame headless. It runs when a release is cut, and you can run it any time to check that the route still works.

## Examples and attribution

Port a sketch only when its license permits redistribution under MIT. Name its source, author, URL, and license in the file header. The header template and the full rules are in [`Examples/README.md`](examples/index.md) and the README's [Influences & attribution](about.md#influences-attribution) section. When you are unsure of a sketch's origin or license, open an issue and ask first.

## Conduct and license

The [code of conduct](code_of_conduct.md) applies to all project spaces. Contributions are accepted under the [MIT license](https://github.com/eaviles/Ollin/blob/main/LICENSE).