Skip to main content

Contributing

Set up​

git clone https://github.com/carneirofc/qttaskmanager.git
cd qttaskmanager
uv sync
uv run python main.py

Tests​

The suite is stdlib unittest, no extra runner required:

uv run python -m unittest discover -s tests

Tests deliberately target the pure-data collectors (*_data.py) and the Qt-free logic, plus focused model/tab and MCP tests. The clean split between UI (*_tab.py) and data (*_data.py) is what keeps them fast and headless — follow it when adding features: put logic that can be tested without a running Qt application in a data module.

Linting​

Ruff runs in CI on every push and pull request:

uvx ruff check .

Keep it clean before opening a PR.

Commit messages​

Commits follow Conventional Commits:

<type>[optional scope]: <description>

Common types: feat, fix, docs, refactor, perf, test, chore, build, ci. Examples from the history:

  • feat(disk): expand cleanup-location coverage and make the scan testable
  • fix(scan): sort numeric columns in Python so large byte sizes order correctly
  • docs(mcp): document MCP tools + agent integration

Documentation​

These docs live under website/ (Docusaurus). To work on them:

cd website
npm install
npm start

Add a page under website/docs/ and list it in website/sidebars.js. Pushing website/ changes to master republishes the site via .github/workflows/docs.yml.

The read-only principle​

The scanners are read-only by design. When adding a scanner, report findings and stop there — leave removal to the user. If you add an operation the MCP server can request, route it through the human-in-the-loop approval broker (mcp_approvals.py); never let a tool act on its own.