# Contributing

Thanks for helping improve Portfolio Tracker.

## Before opening a change

1. Keep the ledger local-first and avoid adding broker credentials.
2. Preserve compatibility with Python 3.11 and current Omarchy Quattro.
3. Add or update focused tests for calculation, import, and provider changes.
4. Keep personal portfolio exports, database files, and snapshots out of Git.

## Validate locally

```bash
python3 -m unittest discover -s tests -v
python3 -m compileall -q portfolio_tracker
python3 -m json.tool manifest.json >/dev/null
omarchy plugin validate .
qmllint -I "$OMARCHY_PATH/shell" BarWidget.qml Panel.qml
```

For UI changes, also verify left-click open/close, Escape dismissal, IPC
summon/hide, shell restart, disable/re-enable, vertical-bar rendering, and a
clean removal. Test both an empty ledger and a multi-account ledger.

## Design notes

`BarWidget.qml` owns the bar surface and loads `Panel.qml`, which owns the
dashboard and local snapshot watcher. The Python package owns ledger math,
market data, imports, and atomic snapshot generation. Keep calculations out of
QML so the CLI, tests, and widget always agree.