1.4.8.1. Change Management

In the governance of large-scale Terraform modules, change management is an indispensable component. Since the governed modules are open-source projects, they not only receive submissions from internal company developers but may also attract code improvements from external contributors. This brings continuous vitality to the module's evolution, but it also presents a challenge: how to ensure that every change is high-quality, secure, and controllable.

This section details the module contribution process and how maintainers can manage changes efficiently and robustly.

1.4.8.1.1. The Importance of Standardizing the Contribution Process

Terraform modules directly manipulate cloud infrastructure. The consequences of errors can range from resource creation failures to the accidental modification or destruction of existing production resources. Therefore, every code change must undergo strict quality and security checks.

Establishing a standardized contribution process not only guarantees the safety and stability of the module itself but also provides a clear path for external contributors, preventing them from investing unnecessary effort due to misaligned expectations.

Below, we explain the process using the change specifications of Azure Verified Modules as an example:

1.4.8.1.2. Early Communication

Before submitting any new features, fixes, or optimizations, contributors should first create an Issue to describe the problem or proposed improvement in detail. This helps the module maintenance team assess feasibility in advance and ensures that the proposed changes align with the module's development direction.

1.4.8.1.3. Branching and Development

Once the proposal is approved, contributors should create a new working branch based on the module repository's main branch. It is recommended to use a clear naming convention, for example:

fix/variable-docs
feature/add-network-acl

This allows maintainers to quickly identify the nature of the changes in the PR list.

1.4.8.1.4. Adhering to Development Standards

During the development process, contributors must ensure:

• All changes comply with the official HashiCorp and Azure Verified Modules specifications.
• The pre-commit hooks are run locally before committing code. This automatically checks code formatting, generates/updates documentation, and performs basic static analysis to ensure the changes meet fundamental requirements.
• AVM provides a check pipeline equivalent to the make pr-check command. This enables credential-free checks to be executed within the container images used by the Continuous Integration pipeline, ensuring consistency with the pipeline environment. A Pull Request that passes the pr-check is effectively guaranteed to pass the preliminary checks of the CI pipeline. You can execute these commands inside the container via ./avm pre-commit and ./avm pr-check.

1.4.8.1.5. Submitting a PR

Upon completion of development, contributors should submit a Pull Request. The PR content should include:

• A clear title and detailed description explaining the changes, the purpose, and potential impacts.
• Completion of all items in the contribution template checklist.

Tip: A comprehensive PR description helps maintainers quickly understand the context, significantly improving review efficiency.

1.4.8.1.6. Automated Checks

After a PR is submitted, the pipeline automatically triggers a series of checks, including:

• Code Formatting Check: Ensures adherence to the module's formatting and style guidelines.
• Basic Functionality Verification: Checks for syntax errors in the module using terraform validate.
• Static Code Analysis: Uses TFLint to perform static syntax analysis on the code. It blocks anti-patterns explicitly forbidden by the code standards, checks if the types and descriptions of standard interface input variables declared in the module match the standards, and verifies that provider version constraints and external module sources comply with standard specifications.
• Documentation Check: Ensures that all documentation is consistent with the actual state of the current Terraform module.
• Policy Rule Check: Ensures that all example code under examples follows the various rules prescribed by the AVM specifications. We will explain this in detail in the subsequent Rules chapter.
• Example Plan Test: Ensures that the example code under examples/ can successfully execute terraform apply, that repeated apply executions do not cause Configuration Drift, and finally confirms that the infrastructure created by the example code can be correctly destroyed via terraform destroy. We will explain this in greater detail in the subsequent chapters on testing.

If any checks fail, contributors should refer to the pipeline output hints to correct the issues and resubmit.

1.4.8.1.7. Maintainer Review

Every PR must undergo a manual review by module maintainers. Key review points include:

• Whether the changes align with the long-term planning of the module.
• Whether there are potential security risks.
• Whether the input/output variables and structural design are reasonable, and if types and descriptions are consistent with the Provider.
• Whether the documentation and examples are complete and easy to understand.

If necessary, maintainers will provide feedback, and contributors should respond actively and make improvements.

1.4.8.1.8. Merge Strategy

After the review is passed, module maintainers will adopt the following merge strategy:

• Create a release branch: Create a new release/<description> branch from the main branch.
• Adjust the target branch of the PR to the release branch.
• Merge the PR into the release branch.
• Initiate a new PR to merge the release branch into the main branch to trigger end-to-end testing.
• Once testing passes, formally merge into the main branch.

This workflow ensures that the main branch always maintains high stability, avoiding the direct merger of potentially unstable changes.

1.4.8.1.9. Handling Failures

If end-to-end testing fails, the module maintainer will:

• Analyze the cause of the failure.
• Decide whether to return it to the contributor for modification or have the maintenance team fix the issue directly, depending on the situation.

Security is always the top priority. Once a security risk is discovered, maintainers have the right to close the PR and report it to the security team if necessary. Issues involving security vulnerabilities and attack attempts must be handed over to a professional team for subsequent handling.

1.4.8.1.10. Summary

Change management is not just a code review process; it is a core element in maintaining module quality and security. By establishing a clear and standardized contribution process, we can provide a good experience for external contributors while ensuring the continuous, high-quality development of the module.