35 lines
2.7 KiB
Markdown
35 lines
2.7 KiB
Markdown
# Repository Guidelines
|
|
|
|
## Project Structure & Module Organization
|
|
- `navipy.py` boots the PySide6 desktop client, wires logging, and discovers modules under `src/`.
|
|
- `src/api/` holds the Subsonic client, auth helpers, and data models that talk to your Navidrome server.
|
|
- `src/accessibility/` and `src/widgets/` contain custom Qt widgets and dialogs with accessibility metadata; `src/main_window.py` composes them.
|
|
- `src/config/settings.py` manages XDG-compliant config/data/cache dirs and persists `settings.json` and `servers.json`.
|
|
- `sounds/` ships UI audio assets; runtime logs land in `~/.local/share/navipy/navipy.log`.
|
|
|
|
## Build, Test, and Development Commands
|
|
- `python3 -m venv .venv && source .venv/bin/activate` — set up an isolated environment.
|
|
- `pip install -r requirements.txt` — install PySide6 and other runtime deps.
|
|
- `python3 navipy.py` — launch the app with logging to the data dir; exit cleanly with Ctrl+C.
|
|
- `pytest` — placeholder for future tests; add a `tests/` folder with `test_*.py` as you grow coverage.
|
|
|
|
## Coding Style & Naming Conventions
|
|
- Follow PEP 8: 4-space indentation, snake_case modules/functions, and descriptive class names for Qt widgets/actions.
|
|
- Keep accessibility in mind: set `setAccessibleName` on interactive widgets, and keep shortcuts consistent with existing ones in `MainWindow`.
|
|
- Prefer type hints for public APIs in `api/` and configuration helpers; keep JSON keys predictable and lowercase.
|
|
|
|
## Testing Guidelines
|
|
- No automated suite exists yet; add `pytest` cases for API client authentication, settings persistence (XDG paths), and any audio/control logic.
|
|
- Name files `tests/test_<feature>.py`; use fixtures to stub Navidrome endpoints instead of hitting real servers.
|
|
- Manual checks still matter: verify keyboard-only navigation, high-DPI rendering, and that logs/config are written under the XDG directories.
|
|
|
|
## Commit & Pull Request Guidelines
|
|
- Write imperative, scoped commit subjects (e.g., "Add server dialog validation"), keep to ~72 chars, and describe user-facing impact in the body when needed.
|
|
- PRs should list the change summary, test results or manual checks, linked issues, and UI screenshots/GIFs for visible tweaks.
|
|
- Call out accessibility-affecting changes, config migrations, or new dependencies so reviewers can double-check regressions.
|
|
|
|
## Security & Configuration Tips
|
|
- Never log server credentials; `servers.json` under `~/.config/navipy/` stores secrets—treat it as sensitive and avoid committing it.
|
|
- Respect `XDG_*` overrides in tests and scripts to avoid polluting real user data; prefer temporary dirs when experimenting.
|
|
- Keep error messages informative but redacted; sanitize Navidrome responses before logging.
|