Contributing

Contributing · Compitum Wiki

Quick-Scan Infobox

Aspect	Details
Target user	Developers extending the router; educators adding examples; anyone reporting issues
Core goal	Guide contributions to code, docs, and issues—ensuring they align with the project's bounded, verifiable approach
Time to first insight	5 minutes: read the infobox and "How to Submit" section
What you get	Clear steps for forking, testing changes, and proposing merges; templates for issues and PRs
Limitations	Contributions must preserve local signals and certificates; no external judges or RL dependencies added
Live resources	Repo at github.com/PaulTiffany/compitum; issue tracker for questions

---

1) What Counts as a Contribution

Contributions to Compitum include code improvements, new observers, wiki pages, or bug reports. Each must maintain the core: decisions via local signals (free energy, coherence) and constraints, with verifiable certificates.

• Code: Add observers, extend constraints, or optimize embedding pools—tested against invariants.
• Docs/Wiki: Clarify concepts, add examples, or fix terminology—following this style guide.
• Issues: Report gaps in signals, constraint violations, or reproducibility problems.
• Other: Translations or benchmarks, if they support auditable routing.

This page focuses on process; see Philosophy for why contributions emphasize mechanistic verifiability over subjective quality.

---

2) Five-Minute Quickstart

Steps (minimal workflow)

1. Fork the repo: Visit github.com/PaulTiffey/compitum and click "Fork".
2. Clone your fork: git clone https://github.com/YOUR_USERNAME/compitum.git.
3. Install: pip install -e . (editable mode for testing).
4. Make a change: Edit a file, e.g., add a comment in compitum/observers.py.
5. Test locally: Run pytest and verify certificates unchanged.
6. Push and PR: git push origin branch-name; open a pull request.

Expected output (from a simple test)

$ pytest tests/observers/test_energy.py
============================= test session starts ==============================
platform linux -- Python 3.12.3, pytest-7.4.0
collected 5 items

tests/observers/test_energy.py .....                                      [100%]

============================== 5 passed in 0.02s ===============================

How to read this: All tests pass, confirming signals (like free energy) compute as expected. If certificates differ, check your shadow price calculations.

---

3) The Contribution Flow

Alt text: Sequence from idea to merge, with branches for review and testing; signals ensure alignment with project invariants.

%% GitHub wiki-safe: <=15 nodes; palette applied in styles
graph TB
  A["Idea or Issue"] --> B["Fork & Clone"]
  B --> C["Create Branch<br/>(e.g., feature/new-observer)"]
  C --> D["Implement & Test<br/>(pytest, invariants)"]
  D --> E["Update Docs<br/>(if changed)"]
  E --> F["Push & Open PR"]
  F --> G["Review: Signals Checked<br/>(free energy, certificates)"]
  G --> H["Merge or Iterate"]

  subgraph Test["Local Checks (signals)"]
    T1["Run pytest"]
    T2["Validate certificate"]
    T3["Check constraints"]
  end

  D --- T1
  D --- T2
  D --- T3

  style Test fill:#fff3e0,stroke:#ef6c00,stroke-width:2px     %% Signals
  style A fill:#e3f2fd,stroke:#1565c0                         %% Learning
  style B fill:#e3f2fd,stroke:#1565c0
  style C fill:#e3f2fd,stroke:#1565c0
  style D fill:#fff3e0,stroke:#ef6c00
  style E fill:#e8f5e9,stroke:#2e7d32                         %% Control
  style F fill:#e8f5e9,stroke:#2e7d32
  style G fill:#fce4ec,stroke:#c2185b                         %% Output
  style H fill:#fce4ec,stroke:#c2185b

Loading

Caption: Branches enforce testing with local signals; reviews confirm no drift in free energy or shadow prices.

---

4) Code Standards (For Developers)

Follow PEP 8 for Python. Use type hints. Preserve terminology: shadow price, free energy, SPD metric, certificate.

• Tests: Every change needs pytest coverage. Include a certificate check: assert JSON matches expected slacks.
• Invariants: No addition of judge-based rewards; signals must be local (e.g., entropy from embeddings).
• Reproducibility: Set seeds in tests; log shadow prices for comparison.

Example Test Snippet

[Notebook content will be embedded by CI]

Montessori Parallel (For Educators Extending Examples):
Montessori: Tasks build on prior work, with built-in checks for self-correction.
Compitum: New examples (e.g., in Cookbook) include runnable code with certificate validation—students see if constraints hold without external grading.

Alt text: Mapping from prepared tasks to verifiable examples.

%% GitHub wiki-safe: simple LR graph; consistent palette
graph LR
  subgraph Classroom
    M1["Self-correcting materials"]
    M2["Sequential tasks"]
  end

  subgraph Examples
    E1["Certificate validation"]
    E2["Reroute with new constraints"]
  end

  M1 --> E1
  M2 --> E2

  style Classroom fill:#e8f5e9,stroke:#2e7d32
  style Examples fill:#e3f2fd,stroke:#1565c0

Loading

Classroom starter: Add a biology example to Cookbook. Have students compute shadow price by hand and compare to the certificate.

---

5) Docs/Wiki Standards (For Writers)

Use this wiki's style: patient explanations, Mermaid for flows, Quick-Scan Infobox per page. No emojis in prose; precise math.

• Changes: Edit Markdown files in /docs or wiki pages directly.
• Review: Ensure time estimates (e.g., "5 mins to first insight") and alt text for diagrams.
• Templates: Use issue/PR templates for doc requests.

Time estimates
• 5–10 minutes: Submit a simple issue or wiki edit
• 20–30 minutes: Add a tested code example
• 45–60 minutes: New observer with docs and tests

---

6) How to Submit

• Issues: Use the tracker. Template: Describe the signal drift or constraint gap; include a prompt example and certificate JSON.
• Pull Requests: Link to an issue if possible. Title: "Add [feature]: [brief why]". Body: Changes, tests passed, shadow price impacts (if any).
• Wiki Edits: Click "Edit" on any page; preview Mermaid rendering.

For questions, open a discussion or issue labeled "question".

---

7) Known Limitations

• Reviews prioritize signal integrity; large refactors need maintainer discussion first.
• No automated CI for wiki yet—manual checks for style.
• Domain-specific observers: Submit as PRs with extension guide updates.

---

8) Reproducibility Notes

• Branch from main; rebase before PR.
• Include pytest --seed=42 outputs in PR descriptions.
• Track certificate changes: Diff JSON before/after.

---

Last updated: 2025-11-07 · Compitum Wiki Contributing