Contributing
Thank you for helping. Be respectful and constructive in issues and reviews, and keep changes focused.
Before you start
Section titled “Before you start”- Set up the project as described in Set up a development environment.
- For a bug, check the existing issues first. For a larger change, open an issue to discuss it before writing the code.
Branches
Section titled “Branches”mainholds the released versions. Never commit to it directly.developcollects the work for the next release. Branches start fromdevelopand pull requests target it.- One branch per change, named after the commit type:
feat/drive-labels,fix/search-crash,docs/building-guide.
Commit messages
Section titled “Commit messages”Commits follow Conventional Commits. The
release version is computed from them, so the type matters: feat gives a minor
version, fix and perf a patch, and a ! after the type (or a
BREAKING CHANGE: footer) a major one.
fix(apis): open a new HTTP session for each search worker
Each search worker runs its own event loop, and an aiohttp session canonly be used on the loop that created it.- Types:
feat,fix,perf,refactor,docs,test,style,build,ci,chore,revert. - Scopes (optional, but only from this list):
video,movies,music,books,games,images,ui,core,apis,config,file-ops,organize,i18n,deps,tools,macos,windows,linux,release,merge,server,web,docker. - Write the subject in the imperative, in English, without a final period. Explain the why in the body.
The lint check of every pull request validates the messages with commitlint
(.commitlintrc.json).
Checks
Section titled “Checks”Run them before pushing; the CI runs the same ones on Linux, and the tests on macOS too:
uv run ruff check srcuv run ruff format --check srcuv run python tools/verify_i18n.pyuv run mypy --install-types --non-interactive src/sok --ignore-missing-imports --no-strict-optionaluv run ty check srcuv run pytest tests/- Type hints on new code, and Google-style docstrings on public functions and classes: they make the API reference.
snake_casefor functions and variables,PascalCasefor classes, a leading underscore for private members.- Every text shown to the user goes through
tr()and is added to the eight language files: see Translations. - Network calls are asynchronous and run in workers, never in the GUI thread.
- A change that affects one system (Windows, macOS, Linux) must leave the others unchanged.
- Add or update tests with the change.
Pull requests
Section titled “Pull requests”- Title in the Conventional Commits format, description in English: what changes, why, and how it was tested.
- Mention the effect on each system when the interface or the packaging changes.
- A pull request is merged when its checks pass and it has been reviewed.
Reporting a bug
Section titled “Reporting a bug”Open an issue with what you did, what
you expected and what happened, your system and the S.O.K version (Settings →
About). Attach the log: sok.log, whose location is given in
Set up a development environment.