A few questions about edge case scenarios

[MaxymVlasov]

1. Module renaming
   1.1. If you rename a module - what will happens with a wiki and CHANGELOG? It will be split to 2 pages, fully migrate to new location, will be copied to new name and only new page will receive updates or something else?
   1.2. What will happen with links to Wiki to this module in previous PRs? They all become broken?

2. Module decommission
   2.1 If you decommission module - is that means that all tags will be removed, so anyone who still uses outdated versions will be pointing to nowhere and get broken infra?
   2.2. If you'll delete tag, you'll lose access to module version, as there will be no way to switch to sha8 as it not in main, and you should know it before tag removal or have that tag in some remote repo to be able to checkout to it. Is it mitigated somehow?
   2.3. Wiki & CHANGELOG will not be accessible right after module decommissioned, so there will be no ability to serve instructions for users how to migrate to new modules/what to use instead?

[virgofx]

Hi @MaxymVlasov - Thanks for your excellent questions about module management. Let me address each point in detail:

1. Module Renaming

1.1 Wiki and CHANGELOG handling

When a module is renamed, the Wiki and CHANGELOG are completely regenerated at the new location. The system doesn't maintain separate versions or split pages - it creates fresh documentation at the new module path. This means historical documentation for the old module name won't persist automatically.

1.2 Previous PR links

Yes, links to the Wiki in previous PRs will unfortunately break after a rename since the old Wiki pages no longer exist. This is a limitation of the current implementation.

2. Module Decommissioning

2.1 Tag removal impact

By default, when decommissioning a module, all tags and releases are removed. This means users of outdated versions would indeed lose their reference points, potentially breaking their infrastructure. However, this behavior can be modified.

2.2 Mitigation for tag deletion

You've identified a critical concern. When a tag is deleted, accessing the specific commit becomes difficult since you'd need to know the exact SHA. We can address this by using the delete-legacy-tags parameter (documented at https://github.com/techpivot/terraform-module-releaser).

Setting delete-legacy-tags to false will preserve all existing tags/releases, allowing users of the old module to continue using it even after decommissioning or renaming. This provides a transition period for migration.

2.3 Wiki and migration documentation

You're right that the Wiki and CHANGELOG become inaccessible immediately after decommissioning. This creates a challenge for providing migration instructions to users but was a conscious design decision of this project to allow for keeping the Wiki up-to-date with formatting/UI updates and other edge cases.

Recommendations:

1. Before renaming/decommissioning modules, consider creating migration documentation elsewhere that won't be affected by the change.
2. Use delete-legacy-tags: false to ensure backward compatibility during transitions.
3. For critical modules, implement a deprecation period with clear notices before complete removal.

Let me know if that helps. If you want me to work on a potential clean rename option (e.g. tags/releases get migrated over) feel free to create a separate issue for me and I can prioritize it.

[MaxymVlasov]

To deal with

1.2 Previous PR links

Yes, links to the Wiki in previous PRs will unfortunately break after a rename since the old Wiki pages no longer exist. This is a limitation of the current implementation.

and

2.3 Wiki and migration documentation

You're right that the Wiki and CHANGELOG become inaccessible immediately after decommissioning. This creates a challenge for >providing migration instructions to users but was a conscious design decision of this project to allow for keeping the Wiki up-to-date >with formatting/UI updates and other edge cases.

I'll recommend you try to push docs not only to Wiki, but alongside module too in some .md file and point PRs not only to wiki but to this .md file using commit reference, not tag

Let me know if that helps. If you want me to work on a potential clean rename option (e.g. tags/releases get migrated over) feel free to create a separate issue for me and I can prioritize it.

Yep, it definitely helps. AFAIK, we will not evaluate any solutions in next few months regarding changing our current "versioning model", but it would be handy to have your tool "enterprise-ready"™ when we will return to this topic.

[MaxymVlasov]

Also, hint about

2.1 Tag removal impact

By default, when decommissioning a module, all tags and releases are removed. This means users of outdated versions would indeed lose their reference points, potentially breaking their infrastructure. However, this behavior can be modified.

2.2 Mitigation for tag deletion

You've identified a critical concern. When a tag is deleted, accessing the specific commit becomes difficult since you'd need to know the exact SHA. We can address this by using the delete-legacy-tags parameter (documented at techpivot/terraform-module-releaser).

Setting delete-legacy-tags to false will preserve all existing tags/releases, allowing users of the old module to continue using it even after decommissioning or renaming. This provides a transition period for migration.

You can note in docs that users can pin their modules to digests using Renovate (here example config - SpotOnInc/renovate-config), so they will not lose access to version if tag will be removed.

I not sure that it will work fine with your tagging strategy, but you can try.

[MaxymVlasov]

Side note: would be nice to add this Q/A as section in docs (plus you can cover other more obvious topics for sure), just to give possible adopters confidence, that your workflow will not fuck up everything in 1 year after adoption :)

UPD. I created separate issues for prev comments, but not for this one with "side note". Feel free to create new issue just for this "side note" and close current issue, or proceed with it in this issue. Or just close it as nobody RTFM, right? 😄
Whatever you choose, it will work for me.