Where to Contribute
===================

The repository is organized around four main pillars. Use this guide to understand the scope of each pillar and to
follow best practices when you open a pull request.

B-UML Language Core (``besser/BUML``)
-------------------------------------

* Own the metamodel: new concepts and relationships start in this folder. Keep naming consistent with the rest of B-UML.
* Update serialization: whenever you add or modify model elements, extend the serializers/deserializers so BUML models
  round-trip cleanly.
* Protect behavior with tests: place unit tests under ``tests/buml`` and cover both valid and invalid scenarios.
* Document everything: reflect the changes in ``docs/source/buml_language.rst`` and any other affected guides to help
  users reason about the new constructs.

Platform Utilities (``besser/utilities``)
-----------------------------------------

* Reuse before reinventing: common converters, validation helpers, and processors should live here so other parts of the
  platform can import them.
* Keep scripts idempotent: utilities are often used in CI and automation, so make sure rerunning them is safe.
* Explain usage: every new tool needs a short README section plus an entry in ``docs/source/utilities.rst`` outlining
  invocation examples and configuration flags.

Code Generators (``besser/generators``)
---------------------------------------

* Mirror the existing layout: split templates, transformers, and configuration objects into separate modules so the
  generator stays maintainable.
* Stay deterministic: generators should produce the same result for the same model; avoid timestamp-based file names
  unless explicitly required.
* Provide samples: include fixtures under ``examples`` or ``tests/generators`` that demonstrate the expected output.
* Wire documentation: annotate ``docs/source/generators`` with usage instructions, prerequisites, and troubleshooting
  tips.

Web Modeling Editor Backend (``besser/utilities/web_modeling_editor/backend``)
------------------------------------------------------------------------------

* Synchronize with the frontend: for every API change, communicate with the UI maintainers and update TypeScript types
  or schemas as needed.
* Cover converters: backend services contain JSON <-> B-UML converters for diagrams; extend both directions and add tests
  whenever you introduce a new concept.
* Respect validation contracts: make sure FastAPI/Flask models, Pydantic schemas, and business rules stay aligned with
  the BUML definitions.
* Document endpoints: update ``docs/source/web_editor.rst`` and ``docs/source/api`` whenever you add, rename, or delete
  API endpoints so integrators can keep up.

Contribution Checklist
----------------------

Regardless of the area:

1. Discuss the idea first (issue tracker or community chat) to avoid duplicated effort.
2. Write or update automated tests that demonstrate the new behavior.
3. Run the relevant commands locally (``pytest``, ``npm test``, ``make docs``, etc.) and ensure they pass.
4. Describe migrations, breaking changes, and manual steps clearly in your pull request description.