computer-playbook/docs/contributing/code/quality.md

Back to Code

Code Quality

Use this page for repository-wide guidance on diff shape, readability, cleanup, and linting.

Diff Quality

• Keep diffs focused, readable, and easy to review.
• Avoid duplicate, conflicting, or purely cosmetic churn unless formatting cleanup is part of the task.
• Prefer semantic improvements that reduce maintenance effort.

Lint

Use these linting and quality tools where applicable:

• ruff
• shellcheck
• hadolint

Repository Lint Rules

Use these repo-wide rules when you add, move, or review files:

• Keep broad folders shallow when that helps readability. Direct children should usually stay at 12 or fewer items per folder.
• Treat structural hubs such as roles/, cli/, tests/unit/plugins/filter, tests/unit/roles, inventories/bundles/servers, inventories/bundles/workstations, plugins/filter, plugins/lookup, group_vars/all, and .github/workflows as intentional exceptions when they are used to organize the tree.
• Prefer smaller, more focused folders over dumping many unrelated files into one directory.

For refactoring guidance, see Development.