Skip to content

Contributing

BDPD welcomes contributions. This page covers the conventions and process for adding code, experiments, and documentation.

Branching Strategy

Branch Purpose
main Stable, deployable (docs website deploys from main)
Feature branches feature/<name> or fix/<name>

Workflow: 1. Create a branch from main 2. Make changes, run lints, verify 3. Open a merge request on GitLab 4. After review, merge to main

Code Style

Python

Configured in pyproject.toml. Enforced by ruff:

ruff check shared/ agents/ experiments/ tools/
ruff check --fix shared/ agents/ experiments/ tools/

Rules enabled: E (pycodestyle), F (pyflakes), I (isort), W (warnings), UP (pyupgrade). Line length: 100 (E501 ignored).

JavaScript

Enforced by ESLint:

npx eslint platform/*.js

The platform uses ES modules ("type": "module"). All imports use import/export syntax.

Pre-Commit Checks

Before pushing or opening a merge request:

# Python lint
ruff check shared/ agents/ experiments/ tools/

# JavaScript lint
npx eslint platform/*.js

# Docs build
mkdocs build --strict

If you're adding new Python entry points, ensure they start with:

from bdpd_check_env import require_venv; require_venv()

How to Add...

...a New Built-in Agent Strategy

  1. Create a class in agents/built-in.js extending BaseAgent
  2. Implement decide(obs) returning a harvest number
  3. Register in STRATEGY_REGISTRY
  4. Add documentation in docs/platform/agents.md

...a New Experiment Sweep

  1. Create a JSON definition file in experiments/definitions/
  2. Format: { "name": "...", "sweep": { ... }, "runs": 30, "config": { ... } }
  3. Run with python experiments/sweep.py --definition <path>
  4. Document in docs/experiments/platform_sweeps.md or supplement_sweeps.md

...a New Card Archetype

  1. Add 20 card definitions to cards/cards_v03.json following the existing schema (id, name, deck, type, count, effects, etc.)
  2. Add faction colours to tools/card_generator/templates/faction_config.json
  3. Run generate_cards.py to verify card images render correctly
  4. Document in docs/cards/archetypes.md

...a New Perturbation Type

  1. Add the type name to PERTURBATION_TYPES in platform/perturbation.js
  2. Add a case in the applyPerturbation() function
  3. The payload is type-specific — follow the existing pattern for before/after state tracking in the changes object
  4. Document in docs/platform/perturbations.md

...a New Documentation Page

  1. Create the .md file under docs/
  2. Add it to the nav section in mkdocs.yml
  3. Preview: mkdocs serve (starts a local server at localhost:8000)

Paper conventions (Quarto books)

The four-paper series in docs/publications/paper_0{0,1,2,3}/ is rendered with Quarto. A few hard-won rules:

  • No non-ASCII Unicode outside math mode in .qmd files. Use $\equiv$ / $k_2$ / $\Delta$ / $\times$ instead of literal ≡ / k₂ / Δ / ×. Headings must stay in plain text — math mode in a heading breaks Pandoc cross-reference labels and silently removes the heading from the TOC.
  • No math inline in pipe-table cells. Pandoc does not process $...$ inside pipe-table cells; the dollar signs render literally in PDF. Either drop math from the cell or move the math outside the table and reword the cell to plain text.
  • Render HTML and PDF together. Use ./scripts/render_publications.sh --which paper_NN (the default, no --pdf-only / --html-only). Both outputs are linked from the docs site and we keep them in sync.
  • Bib hygiene. Only cite works for which a PDF lives in docs/library/<bibkey>.pdf (or a txts/<bibkey>.txt extract). A bare bib entry is not enough — claims must be verifiable. The preflight in render_publications.sh flags unsourced citations.

Re-aggregating partial runs

If a sweep crashes mid-way and you have seed_*/comparison.json files on disk but no aggregate.json, use the standalone reaggregator in scripts/reaggregate_*.mjs rather than re-running the API-hitting pilot. The reducer matches the in-pilot one and reads from disk without touching the LLM.

Repository Policies

  • No secrets. Never commit API keys, tokens, or credentials. Use environment variables.
  • No large binaries. Card art is CC0 and hosted alongside the code; keep images under 1 MB where possible.
  • Licence compliance. New code inherits AGPL-3.0. New documentation inherits CC BY 4.0. Card art must be CC0-compatible.
  • Versioning. Never hardcode version numbers. Use bdpd_version.py which reads from git tags.