Contribute to Caracal
Caracal welcomes bug reports, documentation fixes, tests, SDK improvements, and platform features. This section is the contributor journey from a fresh clone to a merged pull request; the canonical policy lives in CONTRIBUTING.md.
Repository Map
Section titled “Repository Map”The workspace is multi-language: TypeScript applications, Go services, multi-language SDK packages, Docker/Helm infrastructure, and Astro documentation.
| Directory | What lives there |
|---|---|
apps/ | TypeScript applications: the Admin API, Coordinator, runtime CLI, web console, and console auth backend. |
services/ | Go data-plane services: STS, Gateway, and Audit. |
packages/ | SDKs and shared libraries in TypeScript, Python, and Go: core, engine, SDK, identity, OAuth, verify, and adapters. |
infra/ | Docker, Helm, Postgres, Redis, and OpenTofu deployment assets. |
docs/ | This documentation site. |
tests/ | Cross-language test suites and shared fixtures. |
scripts/ | Repository automation for setup, style, tests, and releases. |
Each service, app, and package directory self-documents its rules in an instructions.md file.
Contributor Path
Section titled “Contributor Path”Follow the path in order; each page ends where the next begins.
| Need | Page |
|---|---|
| Prepare your machine | Set Up Locally |
| Learn project boundaries and naming conventions | Follow Project Standards |
| Work on an issue or pull request | Make a Change |
| Run the right checks | Validate Changes |
Maintainer Path
Section titled “Maintainer Path”| Need | Page |
|---|---|
| Understand review, ownership, and security process | Understand Governance |
| Prepare, publish, or recover a release | Release Caracal |
Before You Start
Section titled “Before You Start”- File bugs, documentation gaps, and feature requests through the issue templates. A small focused fix can go straight to a pull request; medium and larger changes start with an issue or proposal before code, as sized in Contribution Scale.
- Report suspected vulnerabilities through Report a Vulnerability, never in public issues.
- Interactions follow the repository Code of Conduct.
- Toolchain versions are pinned in Set Up Locally; no prior knowledge of the repository is assumed beyond those tools.
Next Step
Section titled “Next Step”Start with Set Up Locally before making source changes.