---
title: "Make a Change"
url: "https://docs.caracal.run/contributing/workflow/"
markdown_url: "https://docs.caracal.run/markdown/contributing/workflow.md"
description: "How to plan, implement, validate, and submit Caracal changes."
page_type: "workflow"
concepts: []
requires: []
---

# Make a Change

Canonical URL: https://docs.caracal.run/contributing/workflow/
Markdown URL: https://docs.caracal.run/markdown/contributing/workflow.md
Description: How to plan, implement, validate, and submit Caracal changes.
Page type: workflow
Concepts: none
Requires: none

---

## Standard Flow

1. Start from `main`.
2. Keep the change focused on one component or workflow.
3. Read the relevant service/package instructions before editing.
4. Update docs when behavior, APIs, commands, config, examples, or operations change.
5. Run targeted tests first, then broader checks when shared boundaries changed.
6. Open a pull request with the problem, solution, validation, and risk notes.

## Choose the Area

| Area | Common sources |
| --- | --- |
| Runtime CLI | `apps/runtime`, `packages/engine`, runtime tests. |
| Web console | `apps/web`, Admin SDK, web console tests. |
| API | `apps/api`, migrations, Admin package, API tests. |
| Coordinator | `apps/coordinator`, Coordinator tests, SDK tests. |
| STS/Gateway/Audit | `services/*`, Go tests, operations docs. |
| SDKs/connectors | `packages/*`, language-specific tests, interoperability fixtures. |
| Infra | `infra/docker`, `infra/helm`, Postgres/Redis scripts. |
| Docs | `docs/src/content/docs`, `docs/astro.config.mjs`, generated docs pages. |

## Command Boundary

Do not add top-level runtime CLI commands for zones, policies, grants, audit, agents, delegation, or Control. Human workflows belong to the web console; automation belongs to Control/Admin APIs.

## Security Reports

Do not discuss suspected vulnerabilities in public issues. Use GitHub private advisories or the email path in [Report a Vulnerability](/security/disclosure/).

## Next Step

Use [Validate Changes](/contributing/testing/) to choose the narrowest useful test command before opening a pull request.