From 14a8668486007d9007a9b8ae851d5aa987087c7f Mon Sep 17 00:00:00 2001 From: Martin Atkins Date: Wed, 20 Oct 2021 09:14:34 -0700 Subject: [PATCH] website: "Refactoring" documentation firmer advice about removing moved blocks Co-authored-by: Laura Pacilio <83350965+laurapacilio@users.noreply.github.com> --- .../modules/develop/refactoring.html.md | 20 ++++++------------- 1 file changed, 6 insertions(+), 14 deletions(-) diff --git a/website/docs/language/modules/develop/refactoring.html.md b/website/docs/language/modules/develop/refactoring.html.md index 7e221ce9d..a7381a4c4 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. +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. +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. -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. +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: -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: ```hcl moved {