Module semver "public API": does it include internal module topology?

Terraform
1

Maybe this is a bug. LMK and I’ll be happy to open one.

Modules must* be versioned with semver, but the docs don’t specify what constitutes what a breaking change is? The best I could find is:

https://github.com/hashicorp/terraform/blob/master/website/docs/internals/module-registry-protocol.html.md#module-versions
with the user-facing behavior of the module serving as the “public API”.

What specifically is “user-facing behavior”? What constitutes a breaking change? I’m just guessing, but I’d say:

  • removing or renaming or changing the type of an input or output
  • adding an input that doesn’t have a default
  • maintaining the above but changing the functional behaviour “substantially”. (This is subjective.)

^ This would be nice to have in those docs if I’m correct.

But my question today is: does changing the topology of modules called by the module (and the shuffling about of the resources contained) also constitute a breaking change? Since usually that would imply having to do state surgery.

2

Unfortunately I think the answer to this will tend to depend on the situation, but describing it from the end user’s perspective I think the expectation is that a breaking change is any change which would do any of the following:

  • Make a call that previously worked without errors now produce an error during validate, plan, or apply.
  • Make any of the behaviors described by the module behave in a way different than the previously-documented (or, in the absence of documentation, previously-implied) behavior.
  • Cause any existing infrastructure created via the module to experience downtime, either by being destroyed completely or by being replaced in a way that doesn’t ensure continuity, unless that possibility of downtime was expressly part of the module’s intended design.

In the current design of Terraform, I think it’s true to say that any sort of refactoring that involves renaming resources or moving them into different modules would be a breaking change, because Terraform will understand that as destroying the existing object and creating a new one.

3

Thanks @apparentlymart, very helpful.