69 lines
2.5 KiB
Markdown
69 lines
2.5 KiB
Markdown
|
# 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.
|