Skip to content

Contributing

How to report a problem, set up a development environment, and submit a change.

You can take part in Cortrix in several ways. Here’s a summary, along with the workflow for landing a change. The full rules are in CONTRIBUTING.md in the repository.

Ways to contribute

What you want to doWhere to go
Report a bugThe bug report form. Include steps to reproduce, expected and actual behavior, and your environment
Propose a feature or integrationThe feature and integration form. Use it to confirm scope before you open a large pull request
Improve the docsThe documentation form, or send a focused documentation pull request
Report a security vulnerabilityDon’t open a public issue. See Security boundaries

Licensing and certification

Cortrix doesn’t require a Contributor License Agreement (CLA). Contributions are accepted under the Apache License 2.0, and every new commit must carry a Signed-off-by line certifying the Developer Certificate of Origin 1.1 (DCO).

Add -s when you commit:

git commit -s

To add it to an existing local commit:

git commit --amend --signoff --no-edit

If a contribution has several commits, sign off every one. Contributors keep the copyright in their contributions.

Repository layout

  • cortrix/
    • src/The C++ server implementation
    • include/cortrix/Public C++ headers
    • api/The OpenAPI spec, components, paths, and examples
    • sdk/python/The Python SDK
    • sql-extensions/pgcortrix, the PostgreSQL extension
    • cortrix-mcp/The MCP server
    • cortrix-skills/Framework adapters
    • cortrix-agent/The built-in Agent
    • web/The Web UI
    • deploy/Compose files, Dockerfiles, and configuration
    • tests/C++ tests
    • docs/Documentation

Code comments and names carry short identifiers from the project’s design tracking. The repository’s Feature Index explains them.

Set up a development environment

If you only want to run Cortrix, the Quickstart is all you need. The source build below is for contributors who are changing Cortrix itself.

Prerequisites

ItemRequirement
Operating systemmacOS (arm64 or x86_64) or Linux (x86_64)
CompilerC++17 support: Clang 14 or later, or GCC 10 or later
CMake3.27 or later
OpenSSLInstalled through your system package manager
Python3.9 or later, for the SDK and the MCP server

CMake fetches every C++ dependency automatically.

Build the server

git clone https://github.com/cortrix/cortrix
cd cortrix
mkdir build && cd build
cmake -DCMAKE_BUILD_TYPE=Release ..
cmake --build . --parallel

./cortrix-server --config ../deploy/cortrix.yaml

For faster iteration, you can build without ONNX. Embedding then uses a stub that produces random vectors:

cmake -DCMAKE_BUILD_TYPE=Release -DCORTRIX_USE_ONNX=OFF ..

Python SDK

cd sdk/python
pip install -e ".[dev]"
pytest

Run the tests

Run the C++ tests with ctest from the build/ directory:

cd build
ctest --output-on-failure

You can also run a single suite directly: ./cortrix_unit_tests, ./cortrix_integration_tests, ./cortrix_security_tests, or ./cortrix_stability_tests.

Coding standards

  • Use C++17, in the cortrix::<module> namespace, and match the style of the surrounding code.
  • Use English only in source: comments, log messages, identifiers, and error strings.
  • A new endpoint must return the structured error fields (code, retryable, category, retry_after_ms) and carry the relevant x-cortrix-* hints in the OpenAPI spec.
  • Error codes follow the CX_ERR_* naming convention.

Version number

The VERSION file at the root of the repository is the only place the version is edited by hand. After you change it, synchronize the other locations with the script:

python3 scripts/sync_version.py
python3 scripts/sync_version.py --check

Don’t edit a derived version field on its own. CI runs the check command and rejects version drift.

Pull request workflow

  1. For anything non-trivial, open an issue first.
  2. Branch from the intended base with a short-lived name such as feat/<topic>, fix/<topic>, or docs/<topic>.
  3. Keep each pull request to one logical change.
  4. Add tests for new behavior and keep existing tests passing.
  5. If you change the API, update both api/openapi.yaml and the affected docs.
  6. Sign off every commit under the DCO.
  7. Run the full test suite locally before you push.
  8. Open the pull request against main and describe what changed, why, and how you tested it.

Branches

BranchPurpose
mainThe only integration branch for ongoing development. It doesn’t identify any published version
release/1.0The stabilization and maintenance line for the 1.0 family

Published versions are identified by immutable tags and GitHub Releases. A fix normally lands on main first and then reaches the release line through a separate backport/1.0-* pull request. Delete a pull request’s remote branch once it’s merged or closed.

Code of conduct

Participation is governed by the code of conduct in the repository (CODE_OF_CONDUCT.md). Send conduct reports privately to devrel@cortrix.ai, not through a public issue.

Next steps