mirror of
https://github.com/techno-tim/k3s-ansible.git
synced 2026-08-09 07:23:19 +02:00
Techno Tim
6aea6e71b6
- Add canonical agent and contributor documentation. - Modernize issue and pull request templates. - Skip CI for documentation and issue-template-only changes.
95 lines
3.4 KiB
Markdown
95 lines
3.4 KiB
Markdown
# 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](https://github.com/timothystewart6/k3s-ansible/discussions/20).
|
|
- 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`:
|
|
|
|
```bash
|
|
git switch master
|
|
git pull --ff-only
|
|
git switch -c <type>/<short-description>
|
|
```
|
|
|
|
Create a Python environment and install the pinned development dependencies:
|
|
|
|
```bash
|
|
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](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:
|
|
|
|
```bash
|
|
pre-commit run --all-files
|
|
```
|
|
|
|
For playbook or role changes, run syntax checks:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
molecule test --scenario-name <scenario>
|
|
```
|
|
|
|
See [molecule/README.md](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:
|
|
|
|
```text
|
|
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.
|