Ansible roles development¶
This document describes the conventions and process used by the OME team for developing, maintaining and releasing its Ansible roles.
The set of rules and procedures described below applies to the official OME roles registered in https://github.com/ome/ansible-roles.
The source code of an Ansible role should be maintained under version control using Git and hosted on GitHub under the ome organization. The Git repositories should be named as ansible-role-<ROLENAME>.
Each directory layout should minimally follow the standard Ansible role layout including other files and folders for testing and deployment. A typical role structure is shown below:
defaults/ # Default variables handlers/ # Handlers meta/ # Role metadata main.yml # Dependencies and Galaxy metadata molecule/ # Test tasks/ # Main list of tasks to be executed main.yml templates/ # Role templates .travis.yml # CI/deployment configuration file README.md
the MAJOR version must be incremented when incompatible API changes are made,
the MINOR version must be incremented when functionality is added in a backwards-compatible manner, and
the PATCH version must be incremented when backwards-compatible bug fixes are made.
Final releases must be tagged with a tag matching the version i.e. MAJOR.MINOR.PATCH with no prefix.
Testing and Continuous Integration¶
For each Ansible role, a
molecule folder should be configured allowing
the testing to be tested using Molecule. One or more scenarios should be
configured using at least a Docker driver if possible. A generic
molecule folder can be initialized using the following command:
molecule init scenario -r ansible-role-<NAME> -s default -d docker
Continuous Integration of Ansible roles is performed using Travis CI.
OME Ansible roles are getting progressively upgraded from Molecule 1.x to Molecule 2.x. New roles must be configured using Molecule 2.x.
Distribution and support¶
All core OME Ansible roles should be deployed to Ansible Galaxy under the openmicroscopy organization. All roles must support RHEL/CentOS 7 as a primary platform. New roles should also include Ubuntu 18.04 as a supported platform whenever possible.
The Galaxy role name should be openmicroscopy.<ROLENAME>. For overriding the
default name derived from the GitHub repository name, the role_name variable
should be set in
meta/main.yml. For role names composed of multiple
words, note that the Galaxy import process will convert hyphens to underscores.
Ansible playbooks can consume these roles using a
file - see
for examples of such files.
The release of an Ansible role and its deployment to Galaxy release happens by triggering a role import in Galaxy using the Travis integration on each release tag.
A PGP-signed tag of form x.y.z should be created for the released version using scc tag-release or git tag -s and pushed to the upstream repository:
$ git tag -s x.y.z -m "<tag message>" $ git push origin x.y.z