FOUR-QUADRANT_BALANCE_SHEET_MATRIX/CONTRIBUTING.md

Contributing to FQBM

Thank you for your interest in contributing to the Four-Quadrant Balance Sheet Matrix (FQBM) project.

---

Development setup

git clone <repo>
cd FOUR-QUADRANT_BALANCE_SHEET_MATRIX
python3 -m venv .venv
source .venv/bin/activate   # Windows: .venv\Scripts\activate
pip install -e ".[dev]"     # or pip install -e . && pip install pytest

---

Running tests

pytest tests/ -v

Add new tests under tests/; keep module layout aligned with src/fqbm/.

---

Code style

• Follow existing style in the codebase (PEP 8–style).
• Use type hints for public function parameters and returns where practical.
• Docstrings: include purpose, main parameters, and return value; for IPSAS functions, reference the standard (e.g. IPSAS 3); for regression helpers, note “Required columns” for DataFrames.

---

Adding a new sheet

1. Add a module under src/fqbm/sheets/ (e.g. new_sheet.py) with a step function that takes state and params and returns updated state or a result dict.
2. Wire the sheet into fqbm.workbook.runner.run_workbook() (read initial state, call the step, write result into the workbook result dict).
3. Optionally add export in _export_excel() for the new result key.
4. Add tests in tests/ that call the new step and assert on outputs.

---

Adding a new scenario

1. In src/fqbm/scenarios/presets.py, add a builder function (e.g. _new_scenario()) that returns a ScenarioPreset (name, description, state, optional params and shock_spec).
2. Register it in _build_registry().
3. Optionally add an entry in get_case_narrative() for the structured narrative and key_drivers/suggested_shocks.

---

Documentation

• User-facing: update docs/USER_GUIDE.md and docs/API_REFERENCE.md when adding public API.
• Data: update docs/DATA_DICTIONARY.md for new state fields, sheet I/O, or regression columns.
• Gaps: if adding IPSAS or matrix-related features, update docs/IPSAS_COMPLIANCE.md and docs/GAPS_AND_MISSING.md as needed.
• Changelog: add a short entry under [Unreleased] in CHANGELOG.md.
• Recommendations: see docs/RECOMMENDATIONS.md for the full list of suggestions.

---

Pull requests

• Keep PRs focused; prefer smaller, reviewable changes.
• Ensure tests pass and that new code is covered where practical.
• Update the docs and changelog as above.