Contributor guide
Developer Handbook
A practical guide to contributing safely, consistently and transparently to CORals OIP.
How we build
Domain first
Organise code around Companies, Finance, Governance, Benchmarking, Surveys, HR and analytical capabilities—not transient technical fashions.
Small, testable changes
Keep functions focused. Add regression tests for fixes and unit tests for new repositories, services and infrastructure.
Explicit boundaries
Applications do not query SQL. Analytics does not bypass services. Repositories do not depend on machine learning.
Coding conventions
| Area | Convention |
|---|---|
| Naming | Classes use PascalCase; functions, variables and files use snake_case; constants use UPPER_CASE. |
| Types | Public functions include type hints. Prefer immutable dataclasses for stable knowledge artefacts. |
| Documentation | Public modules/classes have concise docstrings. Explain why where the rationale is not obvious. |
| Dependencies | Respect the documented dependency rules and prevent circular imports. |
Definition of done
- Acceptance criteria are met and scope creep is avoided.
- Tests pass locally; relevant dependency rules are covered.
- Traceability, versions and evidence are retained where applicable.
- Documentation and an ADR are updated when the architecture changes.
Quality principle: the best implementation is one a future contributor can understand, test and replace without disturbing the rest of the platform.
