besser-dev

Contributing to BESSER

This skill covers the procedural workflows for contributing to the BESSER codebase. For architecture details and code conventions, also consult the BESSER repo's CLAUDE.md (auto-loaded in Claude Code; with other agents, read CLAUDE.md at the repo root directly).

---

Development Setup

git clone https://github.com/<your-username>/BESSER.git
cd BESSER
python -m venv venv
# Windows: venv\Scripts\activate
# macOS/Linux: source venv/bin/activate
pip install -r requirements.txt
pip install -r docs/requirements.txt  # for building docs
pip install -e .                       # editable install

Verify: python tests/BUML/metamodel/structural/library/library.py

Python 3.11+ is required (enforced by python_requires = >=3.11 in setup.cfg; CI tests 3.11 and 3.12).

---

Reference layout

This skill keeps SKILL.md short. Reach into references/ for the procedure you need:

Task	Read
Add a new generator (the most common contribution) — 6 steps + scaffold	references/adding-a-generator.md
Add a new metamodel / sub-DSL, plus JSON↔BUML converters	references/adding-a-metamodel.md
Write pytest tests (fixtures, tmp_path, what to assert)	references/testing.md
Build the Sphinx docs and cross-reference them	references/docs-and-build.md
Code style, commit/PR conventions, cross-repo, CI/release	references/contributing-workflow.md

Related skills for the using side (not contributing):

• Running or customizing an existing generator → the besser-generators skill.
• Diagnosing install/import/generation errors → the besser-troubleshooting skill.
• The user-facing shape of a model type (doc templates) → the besser-user skill's references/.

---

Common Contribution Pitfalls

1. Don't duplicate logic — shared helpers go in besser/utilities/, not in individual generators.
2. Maintain determinism — generators must produce identical output for identical input.
3. Keep converters symmetric — if JSON → BUML supports a feature, BUML → JSON must too.
4. Update docs — any backend change likely needs docs/source/ updates.
5. Don't touch the frontend submodule unless explicitly required. UI changes go to the upstream WME repo.
6. Clean up resources — always use try/finally for temp directories and file handles.
7. Test round-trips — especially for converters (JSON → BUML → JSON should be identity).