k3s-ansible/CONTRIBUTING.md

Contributing to k3s-ansible

Thank you for improving k3s-ansible. Contributions should be focused, safe to apply to existing clusters, and tested in proportion to their operational impact.

Before opening an issue

• Search existing issues and discussions for the same behavior.
• Review the troubleshooting discussion.
• Remove tokens, credentials, public IP addresses, private hostnames, and other sensitive values from logs and configuration.
• For support requests, include the k3s-ansible revision, Ansible version, target operating system, architecture, network provider, relevant sanitized variables, and a minimal reproduction.

Use the bug report template for reproducible defects and the feature request template for proposed behavior.

Development environment

Fork and clone the repository, then create a branch from the latest master:

git switch master
git pull --ff-only
git switch -c <type>/<short-description>

Create a Python environment and install the pinned development dependencies:

python3 -m venv .env
source .env/bin/activate
python3 -m pip install -r requirements.txt
ansible-galaxy collection install -r collections/requirements.yml
pre-commit install

Copy ansible.example.cfg to the ignored ansible.cfg file if local Ansible configuration is needed. Start custom inventories from inventory/sample/, keep them out of Git, and never use production credentials in tests.

Making changes

• Keep each pull request focused on one problem or feature.
• Follow AGENTS.md for repository structure, implementation conventions, and safety requirements.
• Preserve idempotence and existing-cluster compatibility.
• Add or update tests for behavior changes and regressions.
• Update role defaults, sample inventory, and documentation when user-facing variables change.
• Consider both provisioning and reset behavior for persistent resources.
• Avoid unrelated reformatting and generated files.

Validation

Run all pre-commit checks before submitting a pull request:

pre-commit run --all-files

For playbook or role changes, run syntax checks:

ansible-playbook site.yml --syntax-check -i inventory/sample/hosts.ini
ansible-playbook reset.yml --syntax-check -i inventory/sample/hosts.ini

Run the most relevant Molecule scenario when Vagrant, VirtualBox, and the required host networking are available:

molecule test --scenario-name <scenario>

See molecule/README.md for scenario details and local requirements. Pull requests should list every check that was run and clearly identify checks that could not be run locally.

Commits and pull requests

Use a conventional commit subject with a scope:

type(scope): short description

Common types are feat, fix, refactor, test, docs, and chore. Write subjects in the imperative mood and keep commits logically focused.

Pull requests should:

• Describe the problem and the resulting behavior.
• Identify compatibility, security, networking, and upgrade risks.
• Include testing evidence without sensitive data.
• Call out documentation and sample configuration changes.
• Link related issues with Fixes #<issue> when applicable.
• Avoid checking boxes for tests that were not run.

Maintainers may ask for a change to be split when unrelated work makes it difficult to review or roll back.