81 lines
2.6 KiB
Markdown
81 lines
2.6 KiB
Markdown
|
# Contributing to Homebase
|
||
|
|
|
||
|
|
Two-person project right now (Daniel + Robert). This doc exists so the conventions don't get lost as the team grows.
|
||
|
|
|
||
|
|
## Dev setup
|
||
|
|
|
||
|
|
```bash
|
||
|
|
git clone https://forgejo.sourcegate.online/daniel/homebase.git
|
||
|
|
cd homebase
|
||
|
|
|
||
|
|
python -m venv .venv
|
||
|
|
source .venv/bin/activate
|
||
|
|
|
||
|
|
# Flask installer
|
||
|
|
pip install -r webinstaller/requirements.txt
|
||
|
|
python webinstaller/app.py # serves on http://localhost:5000
|
||
|
|
|
||
|
|
# Dev tooling (lint + tests)
|
||
|
|
pip install -e ".[dev]"
|
||
|
|
ruff check .
|
||
|
|
pytest
|
||
|
|
```
|
||
|
|
|
||
|
|
Required system tools (used by `webinstaller/drives.py`):
|
||
|
|
|
||
|
|
- `lsblk` (util-linux)
|
||
|
|
- `smartctl` (smartmontools) — `sudo pacman -S smartmontools` / `sudo apt install smartmontools`
|
||
|
|
|
||
|
|
## Commit messages
|
||
|
|
|
||
|
|
We use [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/). Every commit subject line starts with a type:
|
||
|
|
|
||
|
|
| Type | When |
|
||
|
|
|------|------|
|
||
|
|
| `feat:` | New user-visible feature |
|
||
|
|
| `fix:` | Bug fix |
|
||
|
|
| `docs:` | Documentation only |
|
||
|
|
| `ci:` | CI config, Forgejo Actions, runner setup |
|
||
|
|
| `build:` | Packaging, `pyproject.toml`, dependency changes |
|
||
|
|
| `refactor:` | Code restructuring with no behavior change |
|
||
|
|
| `test:` | Adding or fixing tests |
|
||
|
|
| `chore:` | Everything else (e.g. `.gitignore`, version bumps) |
|
||
|
|
|
||
|
|
Examples:
|
||
|
|
|
||
|
|
```
|
||
|
|
feat: add S5 domain picker to installer wizard
|
||
|
|
fix: handle empty lsblk output in drives.parse_size_gb
|
||
|
|
docs: document NS delegation flow for managed gateway
|
||
|
|
ci: add ruff format check to Forgejo Actions workflow
|
||
|
|
```
|
||
|
|
|
||
|
|
Keep the subject line under 72 characters. Use the body to explain *why* — the code already says *what*.
|
||
|
|
|
||
|
|
## Code style
|
||
|
|
|
||
|
|
- **Python:** ruff handles lint + format. Config in `pyproject.toml`. Run `ruff check . && ruff format .` before committing.
|
||
|
|
- **Markdown:** wrap at a sensible width (no hard line-length rule). Every external link you add to a doc must resolve (the markdown-link-check CI job will catch it if it doesn't).
|
||
|
|
- **No comments that explain *what*** — the code says that. Only comment the *why* when it's non-obvious.
|
||
|
|
|
||
|
|
## PR / push workflow
|
||
|
|
|
||
|
|
While the team is two people, pushing to `main` is fine for small changes. For anything larger than ~50 lines or that touches architecture, open a PR and get the other person to look at it.
|
||
|
|
|
||
|
|
## Tests
|
||
|
|
|
||
|
|
Tests live in `tests/`. Pure functions get unit tests; anything that shells out to `lsblk` / `smartctl` is out of scope (those need hands-on testing on real hardware).
|
||
|
|
|
||
|
|
```bash
|
||
|
|
pytest # all tests
|
||
|
|
pytest tests/test_drives.py -v
|
||
|
|
```
|
||
|
|
|
||
|
|
## Releases
|
||
|
|
|
||
|
|
See [RELEASING.md](RELEASING.md).
|
||
|
|
|
||
|
|
## License
|
||
|
|
|
||
|
|
AGPL-3.0 (see `LICENSE`). By contributing you agree your contributions are licensed the same way.
|