Breaking change

As explained in Terraform in Depth: Infrastructure as Code with Terraform and OpenTofu

A breaking change is a software change that makes previously valid code, configuration, or interfaces require modification to function correctly.

A breaking change makes previously valid code, configuration, or interfaces require modification. In infrastructure modules, it can change variable names, required provider information, or behavior introduced by a provider upgrade. section 9.6.1

Common reasons to accept a breaking change include:

• Fixing insecure settings by changing behavior or default values. section 9.6.1
• Renaming variables to improve clarity or consistency. section 9.6.1
• Adapting a module to a provider release that removes deprecated features or requires additional information. section 9.6.1
• Adding functionality that cannot work without changing the existing interface. section 9.6.1

Renaming a module variable

If a module renames a variable, existing users must update their module configuration. Record the change in UPGRADE.md or CHANGELOG.md, group it with related major-version work when practical, and tag a new release after the changes are complete. section 9.6.1 section 9.6.3

Figure 9.2 Major release Git branching

Use the major-release branching diagram to relate breaking changes to parallel development, review, and merging into the main branch. section 9.6.3

How Terraform in Depth: Infrastructure as Code with Terraform and OpenTofu covers it

How deep it goes

Explains causes, batching, provider cascades, tests, and upgrade notes, but gives no detailed migration procedure beyond documenting interface changes.

Examples

Uses insecure defaults, renamed variables, provider requirements, removed deprecated features, major-release branches, and upgrade notes as examples.

What it assumes

Assumes an existing module interface, provider dependency, or test suite whose compatibility can be affected by change.

What you can do after

Apply it by grouping compatible breaking changes, documenting migration instructions, branching major-release work, and using tests to detect regressions.

How it connects

Connects breaking changes with backward compatibility, semantic versioning, provider releases, module interfaces, automated testing, and major releases.

liveBookmanning.com

Read Terraform in Depth: Infrastructure as Code with Terraform and OpenTofu on liveBook Get the book at manning.com

Also explained in

• 

  liveBookmanning.com
  Automating API DeliveryA breaking change is an API modification that can cause existing consumers or integrations to stop working.
• 

  liveBookmanning.com
  Google Anthos in ActionA breaking change is a modification to an interface or behavior that can cause existing dependent clients or services to fail.
• 

  liveBookmanning.com
  Go in Action, Second EditionA breaking change is a modification that can prevent existing consumers from continuing to work without updates.
• 

  liveBookmanning.com
  Building Web APIs with ASP.NET CoreA breaking change is a modification that can cause existing clients or system integrations to stop working correctly.

Compare how 5 books explain breaking change →

Related concepts

• backward compatibilitycontrasts with · Backward compatibility is the property of a changed or newer system remaining usable by existing clients and consumers of its earlier interfaces, behavior, or data.
• versioningaddressed by · The practice of identifying and managing successive revisions of files, data, models, interfaces, or other artifacts so changes can be tracked and earlier states recovered.
• major versionproduces · A major version is the primary component of a version identifier that distinguishes a release line and commonly signals potentially backward-incompatible changes.
• review processaddressed by · A review process is a structured evaluation of work, performance, artifacts, or proposals against relevant criteria to assess quality, progress, correctness, or suitability.
• sunset strategyincludes · A sunset strategy is the planned discontinuation and shutdown of a software component, such as an API or subsystem, after its supported service period.

This explainer was generated by Manning's knowledge graph from the text of Terraform in Depth: Infrastructure as Code with Terraform and OpenTofu. The section links point to the parts of the book it draws on.