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//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).

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: BESSER-PEARL
• Source: BESSER-PEARL/BESSER-Skills
• License: Apache-2.0
• Homepage: https://besser.readthedocs.io

Install and usage instructions live in the source repository linked above.