Collection Development

New Collection

Tip

Recommend copying an existing collection, updating, and removing unused options.

Create a repository and clone it.

Enable submodule summaries and out of date checks.

# Check out of date/uncommitted submodules on push to provide a better
# summary of submodule status.

# Enable submodule summary on main repo commits/status.
git config status.submodulesummary 1

# Check for submodules out of date/uncommitted when pushing main repo.
git config push.recurseSubmodules check

Generate collection structure.

# One-time initialization requires FQCN, however the repository is
# typically flat. Create and move to repository base.
cd ~/git/{REPO}
source ansible.env
ansible-galaxy collection init --init-path . r_pufky.{COLLECTION}
mv -vn r_pufky/{COLLECTION}/* .
rm -rfv r_pufky
mkdir -p plugins/modules  # Optional for Python modules.

Testing

Use community references for examples on specific implementations:

Build and Install

The collection must be built and installed locally to be tested.

Collection must be rebuilt if changes (files or tests) were made.

Any change requires rebuilding, installing AND re-entering directory as inodes change.

# Package auto versions based on galaxy.yml.
ansible-galaxy collection build -f  # -f (force) useful for repeated testing.

# Package is installed to local cache:
# ~/.ansible/collections/ansible_collections/{USER}/{COLLECTION}
ansible-galaxy collection install -f  # -f (force) useful for repeated testing.

Running Tests

Always build and install before running tests.

# Always re-enter between installs - cd ~; cd -
cd ~/.ansible/collections/ansible_collections/{USER}/{COLLECTION}
ansible-test {unit,integration,sanity}

Commits

Decision: Use aggressive deprecation

Supporting (OS) * (OS versions) * (ansible versions) * (python versions) versions exponentially grows and cannot be maintained.

Pick versions to develop against and lock against those for longer periods of time.

Use release table and enable consumers unable to migrate the ability to pickup the burden of maintaining it themselves.

Verify exceptions are accurate.

# Remove debug messaging as needed.
grep -ri fail:
grep -ri debug:
grep -ri msg:

# Only accept valid lint exceptions.
grep -ri todo
grep -ri yamllint  # yamllint
grep -ri noqa  # ansible-lint

# Lint returns clean
yamllint .
ansible-lint .

yamllint and ansible-lint documentation.

Update submodules.

Update galaxy.yml.

galaxy.yml

0644 {USER}:{USER}

# Always update version, links, and dependencies.

# Do not include: testing, environments, caches, IDE settings, or staging
# messages in release tarball.
build_ignore:
  - '*.ansible'
  - '*.gitignore'
  - '*.gitattributes'
  - '*.gitmodules'
  - '*.git'
  - '*.venv'
  - '*.envrc'
  - '*.vscode'
  - '*molecule'
  - 'ansible.env'
  - 'pyproject.toml'
  - 'uv.lock'
  - 'TODO.md'
  - 'COMMIT.md'

Update changelogs/changelog.yaml.

Truncate changelog and use ancestor: {LAST VERSION} to link to previous version changelog.
Use Semantic Versioning 2.0.0 and provide a release table in README.md.
Update links to latest release.
Set alerts to check for new release (or push notifications) for each role.

Release

Release low-level dependencies first

data ➔ deb ➔ srv ➔ arr ➔ game ➔ docs

Build & check release.

# Sanity check size/contents for unwanted inclusions.
ansible-galaxy collection build

Upload new artifact to https://galaxy.ansible.com.

Confirm that collection markdown is formatted correctly (Ansible uses a subset of GFM to render documents and may differ from Github). Rebuild and re-upload as needed.
```
# Alternatively manually upload to Galaxy.
ansible-galaxy collection publish
```
Push github release.