Improve How We Handle Breaking Changes #164

New Issue

mik-tf · 2025-01-14T20:49:20Z

mik-tf commented

2025-01-14 20:49:20 +00:00

Situation

It happens that the grid has updates, e.g. in terraform provider or API, and that users complaint it is:
- either not backward compatible
- or it was not documented nor communicated
The feedback we had from people using the products
people want/need assurances that they'll get a clear warning with details about what's changing or that changes are backward compatible

Specs

Ensure either backward compatibility or clear documentation and communication of new releases and breaking changes

Example with Terraform

E.g. the mount_disk was updated from disk_name to name
- The changes were not transferred in the manual nor was it announce for people using terraform

Example with API

Without having a concrete example, it happened a lot with API and users using them on the grid

Backward Compatibility

First option that comes naturally and is easiest for users, is to have backward compatibility
If this is not possible, we need to document the changes and communicate the changes (See below)

Manual/Docs Possibility

If it's not backward compatible, we need to document the changes. It happens a lot that changes are done but the manual docs aren't in sync with the TF repos' docs.

One thing we could do is to use the TF own repos for docs and build the manual out of this
- This would allow devs+ops to update directly the docs as new releases get done, and the manual would be updated
- As a proof-of-concept, check this Mdbook builder out of github repos: https://github.com/mik-tf/docsmaker

Communication

When there are breaking changes, comms circle could be advised from devs or ops circles and communicate it to the community

# Situation - It happens that the grid has updates, e.g. in terraform provider or API, and that users complaint it is: - either not backward compatible - or it was not documented nor communicated - The feedback we had from people using the products - people want/need assurances that they'll get a clear warning with details about what's changing or that changes are backward compatible # Specs - Ensure either backward compatibility or clear documentation and communication of new releases and breaking changes ## Example with Terraform - E.g. the mount_disk was updated from disk_name to name - The changes were not transferred in the manual nor was it announce for people using terraform ## Example with API - Without having a concrete example, it happened a lot with API and users using them on the grid # Backward Compatibility - First option that comes naturally and is easiest for users, is to have backward compatibility - If this is not possible, we need to document the changes and communicate the changes (See below) # Manual/Docs Possibility If it's not backward compatible, we need to document the changes. It happens a lot that changes are done but the manual docs aren't in sync with the TF repos' docs. - One thing we could do is to use the TF own repos for docs and build the manual out of this - This would allow devs+ops to update directly the docs as new releases get done, and the manual would be updated - As a proof-of-concept, check this Mdbook builder out of github repos: https://github.com/mik-tf/docsmaker # Communication - When there are breaking changes, comms circle could be advised from devs or ops circles and communicate it to the community

mik-tf added the

Story

label 2025-01-14 20:49:20 +00:00

thabeta commented

2025-01-16 14:58:41 +00:00

That's should have been handled with semantic versioning and everything else should have worked the same.

couple of things that got introduced

disk_name
nmenmonic instead of mnemonics
zoslight support

should have bumped the version to 2.0 with zoslight change requests. you could still safely use older versions of this

I'll revisit the tags no problem

That's should have been handled with semantic versioning and everything else should have worked the same. couple of things that got introduced - disk_name - nmenmonic instead of mnemonics - zoslight support should have bumped the version to 2.0 with zoslight change requests. you could still safely use older versions of this I'll revisit the tags no problem

Sign in to join this conversation.