test: add tox configuration file, contribution guide and pr template

.github/pull_request_template.md

@@ -0,0 +1,32 @@
+## Description
+
+Please include a summary of the change and which issue is fixed. Please also include relevant motivation and context. List any dependencies that are required for this change.
+
+## Type of change
+
+- [ ] Bug fix (non-breaking change which fixes an issue)
+- [ ] New feature (non-breaking change which adds functionality)
+- [ ] Breaking change (fix or feature that would cause existing functionality to not work as expected)
+- [ ] This change requires a documentation update
+
+## How Has This Been Tested?
+
+Please describe the tests that you ran to verify your changes. Provide instructions so we can reproduce. Please also list any relevant details for your test configuration
+
+### Test Configuration
+
+```sh
+# Please provide example playbook or CLI command
+$ molecule test -s MY_SCENARIO
+$ tox -f MY_SCENARIO run
+```
+
+## Checklist:
+
+- [ ] I have performed a self-review of my own code
+- [ ] I have commented my code, particularly in hard-to-understand areas
+- [ ] I have made corresponding changes to the documentation
+- [ ] My changes generate no new warnings
+- [ ] I have added tests that prove my fix is effective or that my feature works
+- [ ] New and existing unit tests pass locally with my changes
+- [ ] Any dependent changes have been merged and published in downstream modules

CONTRIBUTING.md

@@ -0,0 +1,105 @@
+# Contributing
+
+## Contribute
+
+- [Fork the repository](/~https://github.com/trfore/ansible-smallstep/fork) on github and clone it.
+- Create a new branch and add your code.
+- Write test that cover the changes and expected outcome.
+- Test your changes locally using `tox`.
+- Push the changes to your fork and submit a pull-request on github.
+
+```sh
+git clone /~https://github.com/USERNAME/ansible-smallstep && cd ansible-smallstep
+git checkout -b MY_BRANCH
+# add code and test
+tox run-parallel
+git push -u origin MY_BRANCH
+gh pr create --title 'feature: add ...'
+```
+
+### Setup a Dev Environment
+
+```sh
+cd ansible-smallstep
+python3 -m venv .venv && source .venv/bin/activate
+python3 -m pip install -r requirements/dev-requirements.txt
+pre-commit install
+```
+
+### Tox: Test Suite
+
+- A local installation of [Docker](https://docs.docker.com/engine/installation/) is required to run the `molecule` test scenarios.
+- All `tox` environments are created within the project directory under `.tox`.
+- The collection is tested using the last three versions of `ansible-core` on a Ubuntu image. Additionally, the collection is tested using the latest `ansible-core` on CentOS and Debian.
+  - NOTE: Some molecule scenarios, `multiple_certs` and `step_ssh`, will generate a docker bridge network for each `tox` environment using the next available subnet, e.g. `172.18.0.0/16`. The default docker network is `172.17.0.0/16`.
+- Extensive code modifications that change how a playbook is written need to be accompanied by test, e.g. molecule scenario, that covers the changes. This will help avoid end-user frustration with faulty code examples in the documentation.
+  - Follow best practices for creating playbooks and handling variables within `playbooks/`, but avoid encrypting files. This will keep encrypted files out of the collection build and avoid issues with [`ansible-lint` #2889](/~https://github.com/ansible/ansible-lint/issues/2889).
+
+```sh
+cd ansible-smallstep
+# list environments and test
+tox list
+# lint all files
+tox -e lint run
+# run a specific test environment
+tox -e py-ansible2.16-default run
+# run a group of tests, e.g. the default molecule scenario
+tox -f default run
+# run all test in parallel
+tox run-parallel
+```
+
+- You can also pass environment variables to tox for: `MOLECULE_IMAGE`, `STEP_CA_VERSION`, and `STEP_CLI_VERSION`. When running multiple test, we highly recommend using `STEP_*_VERSION` variables to avoid hitting GitHub's API rate limiter.
+
+```sh
+MOLECULE_IMAGE='trfore/docker-debian12-systemd' tox -e py-ansible2.16-default run
+STEP_CA_VERSION='0.26.0' STEP_CLI_VERSION='0.26.0' tox -e py-ansible2.16-default run
+# highly recommended
+STEP_CA_VERSION='0.26.0' STEP_CLI_VERSION='0.26.0' tox run-parallel
+```
+
+- For iterative development and testing, the tox molecule environments are written to accept `molecule` arguments. This allows for codebase changes to be tested as you write across multiple distros and versions of `ansible-core`.
+
+```sh
+# molecule converge
+tox -e py-ansible2.16-default run -- converge -s default
+# molecule test w/o destroying the container
+tox -e py-ansible2.16-default run -- test -s default --destroy=never
+
+# exec into the container via tox
+tox -e py-ansible2.16-default run -- login -s default
+# exec into the container
+docker exec -it py-ansible2.16-default bash
+
+# parallel testing
+tox -f default run-parallel -- test -s default --destroy=never
+# remove all containers
+tox -f default run-parallel -- destroy -s default
+```
+
+### Tox: Docsite Preview
+
+- If you are making changes to the docsite, `docs/`, or adding variables, e.g. `argument_specs.yml`, you can build the docsite locally and preview the changes.
+
+```sh
+cd ansible-smallstep
+# build site using tox
+tox -e docs
+# preview the docsite
+python3 -c 'import webbrowser; webbrowser.open_new(".tox/docs/tmp/build/html/index.html")'
+```
+
+### Documentation
+
+- New features or extensive code changes need to be accompanied by documentation in a `argument_specs.yml` and README. This information can be redundant, yet it is often helpful to start with the argument_specs then copy it to a README.
+- Adding a scenario guide, `docs/docsite/rst/guide_*.rst`, to the documentation is also nice for features with many arguments or different configurations.
+
+### Pull Request
+
+- All pull request are run through a more extensive test suite that will validate the collection on multiple OSs and releases, yet local `pre-commit` and `tox` test should provide a good proxy for the github tests.
+
+## Additional References
+
+- [Ansible community guide](https://docs.ansible.com/ansible/devel/community/index.html)
+- [Github Docs: Forking a repository](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/fork-a-repo#forking-a-repository)
+- [Ansible Docs: `ansible-core` support matrix](https://docs.ansible.com/ansible/latest/reference_appendices/release_and_maintenance.html#ansible-core-support-matrix)

extensions/molecule/default/molecule.yml

@@ -22,6 +22,8 @@ provisioner:
   playbooks:
     converge: ${MOLECULE_PLAYBOOK:-converge.yml}
   env:
+    STEP_CA_VERSION: ${STEP_CA_VERSION:-latest}
+    STEP_CLI_VERSION: ${STEP_CLI_VERSION:-latest}
     TARGET_CA: ${MOLECULE_NAME:-ca-server}
   config_options:
     defaults:

extensions/molecule/multiple_certs/molecule.yml

@@ -45,6 +45,8 @@ provisioner:
   playbooks:
     converge: ${MOLECULE_PLAYBOOK:-converge.yml}
   env:
+    STEP_CA_VERSION: ${STEP_CA_VERSION:-latest}
+    STEP_CLI_VERSION: ${STEP_CLI_VERSION:-latest}
     TARGET_CA: ca-server-${MOLECULE_NAME:-01}
     TARGET_CLIENTS: ca-client-${MOLECULE_NAME:-01}
   config_options:

extensions/molecule/step_ssh/molecule.yml

@@ -43,8 +43,8 @@ provisioner:
   playbooks:
     converge: ${MOLECULE_PLAYBOOK:-converge.yml}
   env:
-    STEP_CA_VERSION: ${MOLECULE_STEP_CA_VERSION:-"latest"}
-    STEP_CLI_VERSION: ${MOLECULE_STEP_CLI_VERSION:-"latest"}
+    STEP_CA_VERSION: ${STEP_CA_VERSION:-latest}
+    STEP_CLI_VERSION: ${STEP_CLI_VERSION:-latest}
     TARGET_CA: ca-server-${MOLECULE_NAME:-01}
     TARGET_CLIENTS: ca-client-${MOLECULE_NAME:-01}
   config_options:

galaxy.yml

@@ -1,6 +1,6 @@
 namespace: trfore
 name: smallstep
-version: 1.1.0
+version: 1.1.1
 readme: README.md
 authors:
   - Taylor Fore (/~https://github.com/trfore/)

tox.ini

@@ -0,0 +1,74 @@
+[tox]
+minversion = 4.0.0
+envlist =
+    lint
+    docs
+    py-ansible{2.15, 2.16}-{default,ssh}
+    py-ansible{2.16}-{default,ssh}-{centos, debian}
+    py-ansible{2.16}-{mult}
+
+[testenv]
+description =
+    default-!centos-!debian: Run molecule scenario on Ubuntu (default)
+    ssh-!centos-!debian: Run molecule scenario on Ubuntu (step_ssh)
+    centos-!ssh: Run molecule scenario on CentOS (default)
+    centos-!default: Run molecule scenario on CentOS (step_ssh)
+    debian-!ssh: Run molecule scenario on Debian (default)
+    debian-!default: Run molecule scenario on Debian (default)
+    mult: Run molecule scenario to request multiple server certs (Ubuntu)
+deps =
+    ansible2.15: ansible-core == 2.15.*
+    ansible2.16: ansible-core == 2.16.*
+    docker
+    jmespath
+    molecule
+    molecule-plugins[docker]
+    pytest
+    pytest-testinfra
+commands =
+    default: molecule {posargs:test -s default}
+    ssh: molecule {posargs:test -s step_ssh}
+    mult: molecule {posargs:test -s multiple_certs}
+setenv =
+    ANSIBLE_COLLECTIONS_PATH={work_dir}/{env_name}/.ansible/collections/ansible_collections
+    MOLECULE_EPHEMERAL_DIRECTORY={work_dir}/{env_name}/.cache/molecule
+    MOLECULE_GLOB=./extensions/molecule/*/molecule.yml
+    MOLECULE_NAME={env_name}
+    centos: MOLECULE_IMAGE=trfore/docker-centos9-systemd
+    debian: MOLECULE_IMAGE=trfore/docker-debian12-systemd
+    PY_COLORS=1
+    TOX_ENVNAME={env_name}
+passenv =
+    DOCKER_HOST
+    MOLECULE_IMAGE
+    STEP_CA_VERSION
+    STEP_CLI_VERSION
+
+[testenv:docs]
+description = Build the docsite for local preview
+deps =
+    ansible-core
+    antsibull-docs
+allowlist_externals = bash, chmod
+commands_pre =
+    ansible-galaxy collection install . --force
+    chmod 0700 {env:DOCS_PATH}
+commands =
+    antsibull-docs sphinx-init --squash-hierarchy --use-current --dest-dir {env:DOCS_PATH} trfore.smallstep
+    pip install -r {env:DOCS_PATH}/requirements.txt
+    bash {env:DOCS_PATH}/build.sh
+setenv =
+    ANSIBLE_COLLECTIONS_PATH={work_dir}/{env_name}/.ansible/collections/ansible_collections
+    DOCS_PATH={env_dir}/tmp
+    PY_COLORS=1
+    TOX_ENVNAME={env_name}
+
+[testenv:lint]
+description = Run all linting tasks
+skip_install = true
+deps =
+    pre-commit
+commands =
+    pre-commit run {posargs:--all --show-diff-on-failure}
+setenv =
+    TOX_ENVNAME={env_name}