Contribution Guidelines
Relevant source files
The following files were used as context for generating this wiki page:
Introduction
The SPM Middleware project is an Ansible collection designed for installing middleware required by Cúram Social Program Management (SPM). This collection packages playbooks, roles, modules, and plugins to facilitate internal test and development environments.
Contributions in the form of new roles, playbooks, or modules are encouraged provided they adhere to the project's standards for quality, testing, and automation. Every contribution must undergo validation via Molecule and the Ansible linter to ensure consistency and reliability.
Sources: README.md:1-10, CONTRIBUTING.md:104-106, galaxy.yml:25-27
Minimum Contribution Criteria
To maintain the integrity of the collection, all submissions must satisfy three primary technical requirements:
- Molecule Testing: Every new role or modification must include a Molecule scenario and corresponding tests.
- Idempotency: Tasks must be written such that repeated executions yield the same result without unintended side effects.
- Linting Compliance: Code must pass the Ansible linter, which can be verified using the provided
./scripts/runLint.shscript.
Sources: CONTRIBUTING.md:108-112
Development Environment Setup
Contributors have multiple options for establishing a development environment, ranging from local Python virtual environments to containerized "Docker-in-Docker" (DinD) setups.
Local Python Virtual Environment
Using a venv is recommended to isolate dependencies. Contributors must install requirements from ci-requirements.txt and ensure Docker is running for Molecule testing.
python3 -m venv ~/venv/molecule
. ~/venv/molecule/bin/activate
pip install --upgrade pip
pip install -r requirements.txt
Sources: CONTRIBUTING.md:1-8
Containerized Environment (DinD)
A pre-configured Molecule image is available for development. This allows running tests within a privileged container.
The diagram shows the workflow for using a containerized development environment for testing Ansible roles.
Sources: CONTRIBUTING.md:38-55
Creating New Roles
New roles must follow the standard Ansible structure and include specific metadata for integration with Ansible Galaxy.
Required Role Components
| Component | Description |
|---|---|
README.md | Describes functionality, requirements, and usage. |
meta/main.yml | Contains authorship, license (MIT), and platform support (e.g., EL 7/8). |
tasks/main.yml | The primary entry point for role execution logic. |
molecule/ | Contains the converge.yml and verify.yml for automated testing. |
Sources: CONTRIBUTING.md:129-145, roles/websphere/meta/main.yml:1-25
Role Metadata Standards
Metadata in meta/main.yml must specify supported platforms and minimum Ansible versions (typically 2.9).
Sources: roles/iim/meta/main.yml:10-35, roles/liberty/meta/main.yml:10-30
Testing with Molecule
Molecule is the primary tool for testing roles within the collection. It manages the lifecycle of test instances, including creation, convergence, and verification.
Molecule Execution Flow
This sequence illustrates the automated lifecycle of a Molecule test run, from instance creation to final verification and cleanup.
Sources: CONTRIBUTING.md:16-30
Collection Configuration and Publishing
The galaxy.yml file at the root level defines the collection's identity.
| Variable | Value/Requirement |
|---|---|
namespace | merative |
name | spm_middleware |
version | Must follow Semantic Versioning (e.g., 1.8.8) |
license_file | LICENSE (typically MIT) |
CI/CD Integration
For publishing via Travis CI, the following environment variables are required:
GITHUB_OAUTH_TOKEN: For tagging and publishing releases.ARTIFACTORY_URL,ARTIFACTORY_REPO,ARTIFACTORY_TOKEN: If software installers are sourced from a private Artifactory repository.
Sources: galaxy.yml:1-20, CONTRIBUTING.md:155-165
Summary
The SPM Middleware collection relies on standardized development practices to ensure high-quality automation for SPM infrastructure. By enforcing Molecule testing, linting, and a strict role structure, the project ensures that all contributions are idempotent and ready for internal development use. Successful contributions require properly configured metadata in galaxy.yml and meta/main.yml, alongside a verified testing environment using either local virtual environments or the provided Docker-based Molecule setup.