docs(agent): improve repository guidance [skip ci] (#685)

- Add canonical agent and contributor documentation. - Modernize issue and pull request templates. - Skip CI for documentation and issue-template-only changes.
2026-08-02 16:31:40 -05:00
parent 890d43b339
commit 6aea6e71b6
11 changed files with 492 additions and 119 deletions
@@ -0,0 +1,94 @@
+# 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.