furtka/CONTRIBUTING.md

Contributing to Furtka

Two-person project right now (Daniel + Robert). This doc exists so the conventions don't get lost as the team grows.

Dev setup

git clone https://forgejo.sourcegate.online/daniel/furtka.git
cd furtka

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. 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).

pytest                    # all tests
pytest tests/test_drives.py -v

Releases

See RELEASING.md.

License

AGPL-3.0 (see LICENSE). By contributing you agree your contributions are licensed the same way.