Feedback on breaking API changes

[jandubois]

This should be a discussion item, but this repo doesn't have discussions enabled...

I understand that spinkube is pre-1.0 and breaking changes should be expected. But I still think they should be avoided when possible with reasonable effort (and I may be wrong about reasonable effort here).

I think the following sequence of events would have been much smoother for the users of spinkube:

• Add *.spinkube.dev CRDs as aliases for *.spinoperator.dev CRDs

  All existing deployments would continue to work. If possible generate an event whenever an object is generated with the deprecated CRDs.

• Update spinkube plugin to support the new domain

  When the new CRDs are not installed in the cluster, it could still generate a manifest for the old CRD, but also create a warning for the user to tell them to upgrade the operator.

  This also allows the user to target both an older operator in production and a new operator in development/testing with the same plugin version.

  Over time, as apps get updated, they will be migrated to the new CRDs automatically¹.

• Wait for a long time (6 to 12 months)

• Remove old CRDs from the operator and support from the plugin

  By this time most deployed apps and operators will already have been updated due to he app's lifecycle, and there would be no migration required for most users.

This approach would also eliminate the current issue that you have to upgrade the operator and the spin plugin at the same time, which can be a problem if the operator installation is managed centrally and not by the user themselves.

If you do breaking changes again, especially after 1.0, please consider if such a migration path is possible.

Footnotes

1. Edit: ok, not automatically; users would still need to delete the old instances manually unless special migration code was added to the plugin. ↩

[calebschoepp]

Thanks for the feedback @jandubois. We certainly want to avoid making breaking changes going forward. Certainly if we make a breaking change post 1.0 we will offer an easier migration story like you have laid out above.