Contributing
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 do | Where to go |
|---|---|
| Report a bug | The bug report form. Include steps to reproduce, expected and actual behavior, and your environment |
| Propose a feature or integration | The feature and integration form. Use it to confirm scope before you open a large pull request |
| Improve the docs | The documentation form, or send a focused documentation pull request |
| Report a security vulnerability | Don’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:
To add it to an existing local commit:
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
| Item | Requirement |
|---|---|
| Operating system | macOS (arm64 or x86_64) or Linux (x86_64) |
| Compiler | C++17 support: Clang 14 or later, or GCC 10 or later |
| CMake | 3.27 or later |
| OpenSSL | Installed through your system package manager |
| Python | 3.9 or later, for the SDK and the MCP server |
CMake fetches every C++ dependency automatically.
Build the server
For faster iteration, you can build without ONNX. Embedding then uses a stub that produces random vectors:
Python SDK
Run the tests
Run the C++ tests with ctest from the build/ directory:
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 relevantx-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:
Don’t edit a derived version field on its own. CI runs the check command and rejects version drift.
Pull request workflow
- For anything non-trivial, open an issue first.
- Branch from the intended base with a short-lived name such as
feat/<topic>,fix/<topic>, ordocs/<topic>. - Keep each pull request to one logical change.
- Add tests for new behavior and keep existing tests passing.
- If you change the API, update both
api/openapi.yamland the affected docs. - Sign off every commit under the DCO.
- Run the full test suite locally before you push.
- Open the pull request against
mainand describe what changed, why, and how you tested it.
Branches
| Branch | Purpose |
|---|---|
main | The only integration branch for ongoing development. It doesn’t identify any published version |
release/1.0 | The 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.