Skip to main content

Contributing

Contributions should be focused, tested, and aligned with the runtime model already used by the project.

Audience: Developer

Context: Use this page when preparing changes, opening a pull request, or deciding how documentation updates fit into a code change.

Core Explanation​

The contributor workflow in CONTRIBUTING.md emphasizes:

  • fast, reproducible setup
  • focused changes with one concern per pull request
  • conventional commit messages
  • local validation before review
  • documentation updates whenever behavior changes

Branch And Commit Conventions​

Suggested branch prefixes:

  • feat/<name>
  • fix/<name>
  • docs/<name>
  • refactor/<name>
  • test/<name>

Commit style:

  • feat(core): add scoped mandate validation
  • fix(cli): handle missing workspace config
  • docs(readme): update docker quickstart

Practical Usage​

Run the expected checks before opening a pull request:

pytest
black caracal/ tests/
ruff check caracal/ tests/
mypy caracal/

Or in one sequence:

pytest && black caracal/ tests/ && ruff check caracal/ tests/ && mypy caracal/

Documentation Responsibility​

Update docs when:

  • the command surface changes
  • runtime behavior changes
  • configuration rules change
  • module boundaries or workflows change

Do not leave public behavior changes visible only in code or tests.

Internal Behavior​

The repository is structured so that runtime behavior often crosses multiple layers. A small user-visible change may require updates in:

  • CLI or Flow
  • core modules
  • config or storage helpers
  • tests
  • docs

That is normal in this project and should be treated as one cohesive change, not as unrelated file churn.

Edge Cases And Constraints​

  • Use Alembic for database schema changes.
  • Do not treat enterprise placeholders as a place to document enterprise internals.
  • Docs changes should reference the supported runtime model, not hypothetical alternative deployments.
AI tools
On this page