# Contributing to FQBM

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

---

## Development setup

```bash
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

```bash
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](docs/USER_GUIDE.md) and [docs/API_REFERENCE.md](docs/API_REFERENCE.md) when adding public API.
- Data: update [docs/DATA_DICTIONARY.md](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](docs/IPSAS_COMPLIANCE.md) and [docs/GAPS_AND_MISSING.md](docs/GAPS_AND_MISSING.md) as needed.
- Changelog: add a short entry under `[Unreleased]` in [CHANGELOG.md](CHANGELOG.md).
- Recommendations: see [docs/RECOMMENDATIONS.md](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.