Contributing

We value and encourage community contributions. To get started, please follow these guidelines:

1. Code of Conduct
2. Issues
3. Vulnerabilities
4. Development
5. Pull Requests

1. Code of Conduct

Please read and follow our Code of Conduct.

2. Issues

Engagement starts with an Issue where conversations and debates can occur around bugs and feature requests:

• ✅ Do search for a similar or existing Issue prior to submitting a new one.
• ❌ Do not use Issues for personal support. Use Discussions or StackOverflow instead.
• ❌ Do not side-track or derail Issue threads. Stick to the topic, please.
• ❌ Do not post comments using just "+1", "++" or "👍". Use Reactions instead.

👾 Bugs

• ✅ Do search for a similar or existing Issue prior to submitting a new one.
• ✅ Do describe the bug concisely. Avoid adding extraneous code, logs, or screenshots.
• ✅ Do attach a minimal test or example to demonstrate the bug.

💡 Feature Requests

• ✅ Do search for a similar or existing Issue prior to submitting a new one.
• ✅ Do provide sufficient motivation and use case(s) for the feature.
• ❌ Do not submit multiple unrelated requests within one request.

TIP: Engage as much as possible within an Issue before proceeding with contributions.

3. Vulnerabilities

• ✅ Do refer to our Security Policy for more information.
• ✅ Do report vulnerabilities via this link.
• ❌ Do not open a public Issue or Discussion for security vulnerabilities.

4. Development

🌱 Branches

• feature/* — feature development; PR target is main.
• main — stable branch; tagged releases are cut from here.

🔒 Dependencies

• Python >= 3.10
• uv for environment and dependency management.

📦 Project Setup

# 1. Clone and enter the repo
git clone https://github.com/capitec/dsp-decision-engine.git
cd dsp-decision-engine

# 2. Install all dependencies (creates .venv automatically)
uv sync --all-extras

# 3. Run the tests
uv run pytest

If you are behind a corporate proxy that uses a private CA, uv is already configured to use the system certificate store (system-certs = true in pyproject.toml).

📂 Directory Structure

decider/                  Core library
  cli/                    `decider` CLI (click)
  config/                 Versioned config management
  modules/                Module primitives (expression, join, sequential, union)
  serving/                HTTP servers (Starlette, Sanic)
  templates/              Scaffolding templates and scaffold.py renderer
  magics/                 Jupyter %%module magic
docs/examples/            Example notebooks
projects/                 End-to-end project examples
tests/                    pytest suite
pyproject.toml            Project metadata, dependencies, tool config
uv.lock                   Locked dependency graph (committed)

🏷 Naming Conventions

• ✅ Do follow PEP 8.
• ✅ Do name classes in CamelCase and functions/modules in snake_case.

🔍 Code Quality

• ✅ Do adhere to PEP 8 style guidelines.
• ✅ Do use ruff or black for formatting before opening a PR.

🧪 Testing

• ✅ Do write tests under tests/ using pytest.
• ✅ Do ensure all tests pass before submitting a Pull Request (uv run pytest).

5. Pull Requests

• ✅ Do ensure your branch is up to date with main.
• ✅ Do ensure there are no merge conflicts.
• ✅ Do make sure all tests pass.
• ✅ Do provide a clear description of the changes and their purpose.

TIP: Review the existing codebase and follow the conventions used throughout the project.

---

Thank you for contributing! We appreciate your efforts to improve the project.