diff --git a/website/docs/language/modules/develop/refactoring.html.md b/website/docs/language/modules/develop/refactoring.html.md index 7e221ce9d0..a7381a4c48 100644 --- a/website/docs/language/modules/develop/refactoring.html.md +++ b/website/docs/language/modules/develop/refactoring.html.md @@ -426,23 +426,15 @@ moved { ## Removing `moved` Blocks -Over time, a long-lasting module may accumulate many `moved` blocks. - -It can be safe to remove `moved` blocks in later versions of your module when -you are maintaining private modules within an organization and you know that -all module users have successfully run `terraform apply` with your new module -version. - -However, removing a `moved` block is a generally breaking change -to your module because any configurations whose state refers to the old -address will then plan to delete that existing object instead of move it. - -We recommend that by default module authors retain all historical `moved` -blocks from earlier versions of their modules, in order to preserve the -upgrade path for users of any old version. If later maintence causes you -to rename or move the same object twice, you can document that full history -using _chained_ `moved` blocks, where the new block refers to the existing -block: +Over time, a long-lasting module may accumulate many `moved` blocks. + +Removing a `moved` block is a generally breaking change because any configurations that refer to the old address will plan to delete that existing object instead of move it. We strongly recommend that you retain all historical `moved` blocks from earlier versions of your modules to preserve the upgrade path for users of any previous version. + +If you do decide to remove `moved` blocks, proceed with caution. It can be safe to remove `moved` blocks when you are maintaining private modules within an organization and you are certain that all users have successfully run `terraform apply` with your new module version. + +If you need to rename or move the same object twice, we recommend documenting the full history +using _chained_ `moved` blocks, where the new block refers to the existing block: + ```hcl moved {