1.4.2.1. Semantic Versioning

When governing large-scale Terraform modules, version management is the unshakable foundation. There is a critical distinction between Terraform and other software code: once applied, Terraform code directly impacts real resources in the cloud—creating, modifying, or even deleting infrastructure. Introducing a destructive change can range from causing service interruptions to triggering catastrophic data loss.

This is why we emphasize Semantic Versioning (SemVer): It serves as a vital signal helping users determine, "Is there any risk associated with this update?"

The format of the version number looks like this:

Major.Minor.Patch

For example: 1.4.2, 2.0.0, 0.9.7.

These three numbers represent the following:

1.4.2.1.1. Major Version

When the module undergoes incompatible changes, you must upgrade the major version.

For example: Suppose your module originally had an input parameter named enable_monitoring, and you decide to rename it to monitoring_enabled. If users do not modify their configuration, it will result in a runtime error. This type of modification is classified as a "breaking change," and the major version number must be incremented by 1 (e.g., from 1.x.x to 2.0.0).

simply put: Breaking compatibility = Bump Major Version.

⚠️ Critical Warning: Breaking changes in Terraform modules are not just about "configuration incompatibility." They can lead to cloud resources being destroyed and recreated, or even trigger data loss risks! This is completely different from a standard software upgrade simply "having a bug" and must be treated with extreme caution.

1.4.2.1.2. Minor Version

When you add new features that are backwards compatible to the module, upgrade the minor version.

For instance, if you add a tags parameter allowing users to attach custom tags to resources, but leave the old functionality untouched. In this case, you can upgrade from 1.3.2 to 1.4.0.

Simply put: New functionality without breaking changes = Bump Minor Version.

1.4.2.1.3. Patch Version

When you make small fixes or optimizations, upgrade the patch version.

For example, fixing a typo in the terraform plan output message, or updating the module's documentation. In this scenario, you can upgrade from 1.4.0 to 1.4.1.

Simply put: Bug fixes or minor improvements = Bump Patch Version.

1.4.2.1.4. Why Semantic Versioning Is Critical

For us, the role of SemVer is far more than just "looking professional." It achieves the following:

• Instant Clarity: Users can tell at a glance if there is risk and if they need to spend time checking their configuration.
• Integration with Automation: Tools like the Terraform Registry use SemVer to determine if dependencies meet requirements, and CI/CD pipelines can use it to control upgrade strategies.
• Reduced Communication Costs: You don't need to explain to users every time whether "this upgrade is painless"—the version number speaks for itself.

1.4.2.1.5. Centralized Governance: Major Version Update Windows

Although the definition of SemVer itself is clear, the unique nature of Terraform modules dictates a new requirement for large-scale governance:

Breaking changes cannot be released casually!

If the module you maintain is used by a small internal team, upgrading the major version at any time isn't a big issue. But once you are managing hundreds of modules serving hundreds of teams or even external customers, frequently pushing breaking changes is a disaster—no one has the bandwidth to constantly monitor upgrade documentation.

Therefore, our governance recommendation is:

✅ Establish a globally unified "Major Version Update Window," such as opening it once every six months or annually.

During this window:

• Module maintainers can centrally release major version upgrades, bundling all planned breaking changes.
• Detailed upgrade documentation must be provided, clearly specifying:
• Exactly which parameters, outputs, or logic have changed;
• How to modify existing configurations to adapt to the new version;
• Potential cloud-side risk warnings (e.g., which resources will be destroyed and recreated).

You should even consider providing tools to help users with code migration, such as mapotf which we will introduce later.

This is equivalent to "introducing risk according to a plan," which drives the continuous evolution of modules while ensuring users have sufficient time and resources to prepare.

1.4.2.1.6. A Practical Example

Suppose you maintain a module named terraform-aws-network:

Here, 2.0.0 is released utilizing the Major Version Update Window, releasing destructive changes accumulated over six months or a year in one go, thereby reducing the upgrade burden on users.

1.4.2.1.7. Summary

In one sentence: Semantic Versioning is not just a specification; it is the lifeline of Terraform module governance.

For large-scale governance:

• Small changes ➔ Patch Version.
• New features ➔ Minor Version.
• Breaking changes ➔ Major Version + Centralized Update Window.

Planning ahead and providing clear warnings are the only ways to build user trust.