Code Quality and Linting
Relevant source files
The following files were used as context for generating this wiki page:
The spm-middleware project enforces strict code quality standards to ensure the reliability and maintainability of the Ansible collection used for installing Cúram Social Program Management (SPM) middleware. Code quality is maintained through automated linting, sanity testing, and a rigorous Molecule-based testing framework that verifies idempotency and correct state transitions.
Contributions to the project must meet minimum criteria, including passing the Ansible linter and maintaining a comprehensive Molecule test scenario. The linting process covers multiple languages and formats used in the repository, including Python, YAML, and Shell scripts.
Sources: CONTRIBUTING.md:120-125, README.md:1-5
Linting Tools and Configuration
The project utilizes a combination of industry-standard tools to validate the codebase. These tools are orchestrated primarily through a centralized linting script and are required for any local or CI-based development.
Core Linting Components
| Tool | Purpose | Source File |
|---|---|---|
| Ansible Linter | Validates Ansible playbooks, roles, and best practices. | CONTRIBUTING.md:125 |
| YAML Linter | Ensures correct syntax in .yml and .yaml files. | CONTRIBUTING.md:180 |
| ShellCheck | Identifies issues in shell scripts (e.g., databaseUtil.sh). | tests/sanity/ignore-2.11.txt:3-10 |
| Pylint / PEP8 | Enforces Python coding standards for modules and helper scripts. | tests/sanity/ignore-2.11.txt:11-14 |
Automated Linting Execution
The primary entry point for linting is the ./scripts/runLint.sh script. Developers are required to run this script before submitting contributions to ensure compliance with project standards.
# Mandatory check for contributions
./scripts/runLint.sh
Sources: CONTRIBUTING.md:125, galaxy.yml:50
Sanity Testing and Exclusions
To manage the evolving nature of Ansible and third-party tools, the project maintains "ignore" lists for sanity checks. These lists allow the project to acknowledge specific known issues or non-standard implementations that are deemed acceptable for the current version of the collection.
The following diagram illustrates how the linting and sanity check process flow integrates into the development cycle:
The diagram shows the validation path from code changes to final Molecule testing, highlighting the role of ignore lists in the validation process.
Sanity Ignore Lists
File paths like tests/sanity/ignore-2.11.txt define specific rules to bypass during the ansible-test sanity process. Common exclusions include:
- validate-modules: Skips license checks for specific modules (e.g.,
iim_info.py). - shellcheck: Skips specific ShellCheck warnings (e.g., SC2006, SC2086) for complex utility scripts.
- pylint/pep8: Skips Python linting for legacy or third-party compatible scripts like
configOHS.py.
Sources: tests/sanity/ignore-2.11.txt:1-18, CONTRIBUTING.md:145-150
Molecule Verification Framework
Molecule is the primary tool for verifying role quality. It goes beyond static analysis by converging a real environment and running verification playbooks.
Verification Logic
Quality is ensured by asserting the state of the system after a role execution. This includes checking installed packages via custom modules like merative.spm_middleware.iim_info and slurping configuration files to verify internal content.
The sequence diagram demonstrates the verification flow where Molecule interacts with a test host to validate the actual state of the middleware after installation.
Acceptance Criteria
A role is considered high quality and ready for merge only if it:
- Is Idempotent: Running the same playbook twice results in zero changes on the second run.
- Passes Assertions: All tests in
molecule/*/verify.ymlpass (e.g., verifyingWAS_HOMEis set correctly). - Matches Metadata: Versioning in
galaxy.ymland platform support inmeta/main.ymlare consistent.
Sources: CONTRIBUTING.md:120-130, molecule/__websphere-v90/verify.yml:15-40, galaxy.yml:13-15
Dependency Management for Quality
Code quality tools require a specific Python environment. The project provides ci-requirements.txt to standardize these dependencies across local development and CI/CD pipelines.
| Requirement | Usage |
|---|---|
molecule[ansible] | Core testing framework. |
molecule[docker,lint] | Docker driver and linting extensions. |
yamllint | YAML structure validation. |
Sources: CONTRIBUTING.md:145-150, ci-requirements.txt (referenced in project structure)
Conclusion
Code quality in the spm-middleware repository is a multi-layered process combining static linting via runLint.sh, version-specific sanity management through ignore files, and dynamic verification via Molecule scenarios. This ensures that every contribution to the SPM middleware suite is robust, idempotent, and compliant with Ansible collection standards.