snapp / template-ansible-collection Goto Github PK

View Code? Open in Web Editor NEW

2.0 2.0 2.0 118 KB

This Cookiecutter Template can be used to initialize an opinionated project structure for an Ansible Collection.

License: GNU General Public License v3.0

Python 100.00%

template-ansible-collection's People

Contributors

Stargazers

Watchers

Forkers

brandor5 daleroux

template-ansible-collection's Issues

Add (optional) Molecule 6 support for testing playbooks + roles within the collection

The template user should be prompted for whether they want to include Molecule testing (default is yes).

At minimum, the Molecule extension structure should have a default scenario for podman ubi8-init and ubi9-init images with a converge.yml containing a commented example of a role inclusion along with a TODO entry.

Lack of yamllint check

While testing the template I noticed there is no run for yamllint. Is this something you'd like to include in the pre-commit hooks?

 yamllint .
./galaxy.yml
  24:81     error    line too long (82 > 80 characters)  (line-length)
  29:81     error    line too long (108 > 80 characters)  (line-length)

./.github/settings.yml
  3:81      error    line too long (156 > 80 characters)  (line-length)
  18:81     error    line too long (94 > 80 characters)  (line-length)
  21:81     error    line too long (133 > 80 characters)  (line-length)
  24:81     error    line too long (94 > 80 characters)  (line-length)
  27:81     error    line too long (90 > 80 characters)  (line-length)
  30:81     error    line too long (119 > 80 characters)  (line-length)
  83:81     error    line too long (114 > 80 characters)  (line-length)
  91:81     error    line too long (269 > 80 characters)  (line-length)
  93:81     error    line too long (86 > 80 characters)  (line-length)
  97:81     error    line too long (91 > 80 characters)  (line-length)
  99:81     error    line too long (174 > 80 characters)  (line-length)
  103:81    error    line too long (98 > 80 characters)  (line-length)
  105:81    error    line too long (94 > 80 characters)  (line-length)
  107:81    error    line too long (162 > 80 characters)  (line-length)

./.github/workflows/ansible-lint.yml
  6:1       warning  truthy value should be one of [false, true]  (truthy)
  12:81     error    line too long (135 > 80 characters)  (line-length)

./.github/workflows/ansible-test.yml
  3:81      error    line too long (110 > 80 characters)  (line-length)
  21:1      warning  truthy value should be one of [false, true]  (truthy)
  22:81     error    line too long (88 > 80 characters)  (line-length)
  28:81     error    line too long (160 > 80 characters)  (line-length)
  63:9      warning  comment not indented like content  (comments-indentation)
  94:81     error    line too long (87 > 80 characters)  (line-length)
  102:9     warning  comment not indented like content  (comments-indentation)
  128:81    error    line too long (94 > 80 characters)  (line-length)
  147:81    error    line too long (93 > 80 characters)  (line-length)
  188:11    warning  comment not indented like content  (comments-indentation)

./.github/workflows/antsibull-docs-lint.yml
  2:81      error    line too long (116 > 80 characters)  (line-length)
  6:1       warning  truthy value should be one of [false, true]  (truthy)
  12:81     error    line too long (165 > 80 characters)  (line-length)

./changelogs/changelog.yml
  1:1       warning  missing document start "---"  (document-start)

./changelogs/config.yml
  1:1       warning  missing document start "---"  (document-start)
  12:1      error    wrong indentation: expected at least 1  (indentation)

./docs/links.yml
  2:81      error    line too long (98 > 80 characters)  (line-length)
  4:81      error    line too long (84 > 80 characters)  (line-length)
  5:81      error    line too long (84 > 80 characters)  (line-length)
  6:81      error    line too long (95 > 80 characters)  (line-length)
  11:81     error    line too long (93 > 80 characters)  (line-length)
  12:81     error    line too long (93 > 80 characters)  (line-length)
  13:81     error    line too long (87 > 80 characters)  (line-length)
  14:81     error    line too long (97 > 80 characters)  (line-length)
  17:81     error    line too long (83 > 80 characters)  (line-length)
  18:81     error    line too long (85 > 80 characters)  (line-length)
  21:81     error    line too long (83 > 80 characters)  (line-length)
  32:81     error    line too long (84 > 80 characters)  (line-length)
  35:3      warning  comment not indented like content  (comments-indentation)
  38:81     error    line too long (83 > 80 characters)  (line-length)
  39:81     error    line too long (90 > 80 characters)  (line-length)

Add role structure to collection's roles directory

As of this writing, the majority of collections are used to contain roles. As such, we should capture a role_name and role_description to prepopulate the collection with an initial role structure.

Ansible-lint violations

pre-commit run --all-files
Ansible-lint.............................................................Failed
- hook id: ansible-lint
- exit code: 2

INFO     Identified /home/bsawyers/work/scratch/brandor5/cc_testing as project root due .git directory.
INFO     Set ANSIBLE_LIBRARY=/home/bsawyers/.cache/ansible-compat/6ff13f/modules:/home/bsawyers/.ansible/plugins/modules:/usr/share/ansible/plugins/modules
INFO     Set ANSIBLE_COLLECTIONS_PATH=/home/bsawyers/.cache/ansible-compat/6ff13f/collections:/home/bsawyers/.ansible/collections:/usr/share/ansible/collections
INFO     Set ANSIBLE_ROLES_PATH=/home/bsawyers/.cache/ansible-compat/6ff13f/roles:roles:/home/bsawyers/.ansible/roles:/usr/share/ansible/roles:/etc/ansible/roles
INFO     Running from /home/bsawyers/work/scratch/brandor5/cc_testing : ansible-galaxy collection install -vvv --force .
INFO     Loading ignores from .gitignore
INFO     Excluded: .git
INFO     Set ANSIBLE_LIBRARY=/home/bsawyers/.cache/ansible-compat/6ff13f/modules:/home/bsawyers/.ansible/plugins/modules:/usr/share/ansible/plugins/modules
INFO     Set ANSIBLE_COLLECTIONS_PATH=/home/bsawyers/.cache/ansible-compat/6ff13f/collections:/home/bsawyers/.ansible/collections:/usr/share/ansible/collections
INFO     Set ANSIBLE_ROLES_PATH=/home/bsawyers/.cache/ansible-compat/6ff13f/roles:roles:/home/bsawyers/.ansible/roles:/usr/share/ansible/roles:/etc/ansible/roles
WARNING  Listing 8 violation(s) that are fatal
yaml[line-length]: Line too long (269 > 160 characters)
.github/settings.yml:91

yaml[line-length]: Line too long (174 > 160 characters)
.github/settings.yml:99

yaml[line-length]: Line too long (162 > 160 characters)
.github/settings.yml:107

yaml[truthy]: Truthy value should be one of [false, true]
.github/workflows/ansible-lint.yml:6

yaml[truthy]: Truthy value should be one of [false, true]
.github/workflows/ansible-test.yml:21

yaml[truthy]: Truthy value should be one of [false, true]
.github/workflows/antsibull-docs-lint.yml:6

yaml[line-length]: Line too long (165 > 160 characters)
.github/workflows/antsibull-docs-lint.yml:12

yaml[indentation]: Wrong indentation: expected at least 1
changelogs/config.yml:12

Read documentation for instructions on how to ignore specific rule violations.

                Rule Violation Summary                
 count tag               profile rule associated tags 
     1 yaml[indentation] basic   formatting, yaml     
     4 yaml[line-length] basic   formatting, yaml     
     3 yaml[truthy]      basic   formatting, yaml     

Failed: 8 failure(s), 0 warning(s) on 23 files. Last profile that met the validation criteria was 'min'.

check for added large files..........................(no files to check)Skipped
check python ast.....................................(no files to check)Skipped
check that executables have shebangs.................(no files to check)Skipped
check json...........................................(no files to check)Skipped
check for merge conflicts............................(no files to check)Skipped
check for broken symlinks............................(no files to check)Skipped
check yaml...........................................(no files to check)Skipped
fix end of files.....................................(no files to check)Skipped
fix python encoding pragma...........................(no files to check)Skipped
mixed line ending....................................(no files to check)Skipped
pretty format json...................................(no files to check)Skipped
fix requirements.txt.................................(no files to check)Skipped
trim trailing whitespace.............................(no files to check)Skipped
rst ``code`` is two backticks........................(no files to check)Skipped
rst directives end with two colons...................(no files to check)Skipped
rst ``inline code`` next to normal text..............(no files to check)Skipped

Add a pipeline to the collection that can build and publish the collection's artifact

The resulting collection produced by this template should contain a reference implementation of a pipeline capable of building the collection's artifact and publishing it.

Ideally this pipeline would be configured via environment variables to point to the publishing target (i.e., private automation hub or galaxy.ansible.com) along with whatever credentials are required.

This will necessitate using an API Gateway with OIDC as the Private Automation Hub will have restricted network connectivity and not be directly accessible to the GitHub Runner

A reference implementation can be found in the actions-oidc-gateway-example GitHub project

Modify template to allow user to select their preferred license

Users of this template should be enabled to select their license of choice and even be presented with the option to not include a LICENSE file.

As such, the template should offer the following standardized short identifier choices from the SPDX License List:

GPL-3.0-or-later (default)
AGPL-3.0-or-later
Apache-2.0
MIT
BSD-3
None

The human readable prompt should include a reference to https://opensource.guide/legal

IMPORTANT
Some licenses will require the year to be templated into the LICENSE file

Modify template to allow user to select their target SCM repository manager

Users of this template should be enabled to select their target Source Code Management (SCM) repository (e.g., GitHub, GitLab, Azure DevOps)

Currently the template is hard coded for GitHub, but we already have a request for Azure DevOps support.

As such, the template should offer the following choices (with GitLab support added later):

GitHub
Azure DevOps

The resulting collection directory structure should only contain references to their selected SCM Repository manager (e.g., galaxy.yml, pipeline definitions, repo settings, etc.)

Add explanation of cookiecutter variable overrides to the README.md

Explain how cookiecutter variable defaults can be silently overridden using ~/.cookiecutterrc or explicitly overridden by passing a yaml configuration file at runtime via the --config-file parameter.

Both approaches just need a default_context section with the overrides defined similar to this example:

---
default_context:
  author: "[email protected]"
  namespace: "snapp"

Add validation of user input prior to template generation

Cookiecutter supports a "hook" that can be run prior to the template contents being generated (i.e., pre_gen_project).

This pre_gen_project hook could be used to validate the user inputs to ensure the resulting collection is valid.

See: Cookiecutter Documentation / Advanced Usage / Hooks

Add description of tools to the CONTRIBUTING.md

Describe the different tools and features this project makes use of.

Add a pipeline that tests the resulting collection produced by this template

At minimum, this project requires a pipeline that validates:

template successfully generates an ansible collection
generated ansible collection passes pre-commit run --all-files checks

Modify template so docs support is optional while differentiating community versus certified

Users of this template may not require full docs support for their Ansible Collection.

As such, the template should offer the following choices:

none (default)
community collection
certified collection

The contents of the docs directory should be populated as follows:

none - docs directory should not exist
community collection - docs/docsite/rst directory structure with example structure in reStructuredText format for docs.ansible.com
certified collection - docs directory with example structure in markdown format for Automation Hub

Any docs related pipelines should be modified as necessary or removed if none is selected.

See: Developing Collections / docs directory

Modify template so antsibull changelog support is optional

Most users of this template will not require the overhead of tracking a changelog for their Ansible Collection.

As such, the template should ask whether antsibull-changelog support should be enabled.

If not, all traces of antsibull-changelog should be absent from the generated template output.

Add pipeline to test the cookiecutter template to ensure the resulting collection passes `pre-commit run --all-files`

MVP would be to prevent merge requests from happening if linting issues (pre-commit) are present.

Addition of README.md and a few minor changes in galaxy.yml

The README.rst should be renamed to README.md. Only README.md files are supported by Ansible.

https://docs.ansible.com/ansible/latest/dev_guide/developing_collections_structure.html#collection-directories-and-files

A few minor changes in galaxy.yml to support the change, plus minor additions.

Add "not supported" verbage to the README.md

It should be clear to the user of this project that it's not supported by Red Hat in any way; use at their own risk, there be dragons here, etc.

Update user input prompts to be more human readable

Cookiecutter supports associating strings of text with each variable allowing a more polished user experience when being prompted for input.

Add scheduled code drift testing workflow

As an admin I want to be aware of any upstream changes to the tools I'm using that would effect the code I'm writing.

For example the linting workflow is hardcoded to use version 3.0.0 of the pre-commit action. What happens when there is a change to pre-commit after 3.0.0 that negatively impacts my code?

A scheduled workflow (not run on push, PR, etc) that runs against the main branch of the pre-commit action would give me this visibility.

Thinking down the line, how should we represent this in the template itself? One thought is to have a workflow defined but commented out so that it doesn't run by default. This would give users an example without introducing extra work that they are unprepared for. Is there some form of action variables that we could overload? Is this too complicated?