# Contributing

Start with a [source build](https://philbotar.github.io/OpenFlow/getting-started/build-from-source.html), then find the owning area and checks for your change.

## Make a change

1. Check the working tree. Preserve existing staged, unstaged, and untracked work.
2. Find the owner in [AGENTS.md](https://github.com/philbotar/OpenFlow/blob/main/AGENTS.md) and read that area's guide.
3. Implement in that layer, following [Coding patterns](https://philbotar.github.io/OpenFlow/contributing/coding-patterns.html) for ownership, errors, persistence, and test placement.
4. Run checks for the affected behavior and inspect the diff. Update product docs when behavior changes.
5. Run the full verification gate before a code PR. Report local checks, live-provider smoke, and remote CI separately.

## Choose guidance for the change

| Task | Guide |
| --- | --- |
| Launch a local development build | [Build from source](https://philbotar.github.io/OpenFlow/getting-started/build-from-source.html) |
| Look up commands | [Development commands](https://philbotar.github.io/OpenFlow/contributing/commands.html) |
| Fix compilation, cache, or test failures | [Build and test troubleshooting](https://philbotar.github.io/OpenFlow/contributing/build-troubleshooting.html) |
| Find the owner and checks | [Development lanes](https://philbotar.github.io/OpenFlow/contributing/development-lanes.html) |
| Place logic and follow runtime conventions | [Coding patterns](https://philbotar.github.io/OpenFlow/contributing/coding-patterns.html) |
| Verify behavior without the desktop UI | [Testing workflows](https://philbotar.github.io/OpenFlow/contributing/testing-workflows.html) |
| Bump versions, tag, and publish a release | [Releasing](https://philbotar.github.io/OpenFlow/contributing/releasing.html) |
| Build or publish the documentation website | [Documentation website](https://philbotar.github.io/OpenFlow/contributing/documentation-site.html) |
| Trace a run across layers | [End-to-end runtime](https://philbotar.github.io/OpenFlow/architecture/end-to-end-runtime.html) |
| Check dependency rules | [Architecture contract](https://philbotar.github.io/OpenFlow/architecture/contract.html) |
| Look up engine and app vocabulary | [Glossary](https://philbotar.github.io/OpenFlow/glossary.html) |

Project skills in [`.cursor/skills/`](https://github.com/philbotar/OpenFlow/tree/main/.cursor/skills) give scoped help; [Development lanes](https://philbotar.github.io/OpenFlow/contributing/development-lanes.html) maps them to changes.

## Verify and submit

[Development lanes](https://philbotar.github.io/OpenFlow/contributing/development-lanes.html) picks the checks; [Development commands](https://philbotar.github.io/OpenFlow/contributing/commands.html) lists them. Docs-only edits need link, path, syntax, and diff checks. Runtime changes need execution coverage; desktop changes need the desktop lane.

Publishing tags and releases needs explicit authorization. The [release guide](https://philbotar.github.io/OpenFlow/contributing/releasing.html) covers versioning and publication.

Code orientation: [Ports and public boundaries](https://philbotar.github.io/OpenFlow/FOLDER_STRUCTURE.html#ports-and-public-boundaries), [UI layout](https://philbotar.github.io/OpenFlow/FOLDER_STRUCTURE.html#ui-layout), [Persistence locations](https://philbotar.github.io/OpenFlow/architecture/orchestration-layout.html#persistence-locations).

Fast checks and the full gate: [verification command reference](https://philbotar.github.io/OpenFlow/contributing/commands.html#verification-quick-path).