[DOC]: Add migration guide for YAMLs #338

New issue

Open

opened 2024-04-30 13:56:39 +00:00 by synchon · 0 comments

synchon commented

2024-04-30 13:56:39 +00:00

(Migrated from github.com)

We have a strict deprecation cycle!

Gotta move fast 🏎️

Anyways, let's force users to adapt. Maybe we can add a "deprecation" section on the DOCs? So users can somehow know easily how to adapt their old YAMLs?

There is a dedicated section in the changelog docs. But after the examples are improved, should be straightforward for users to adapt.

The changelogs have the information, but my take is that this is not enough. For me it happens that I might start working on a version that it does not even warns a deprecation and then update to a one that already removed the feature or changed the api.

My idea was to create a "guide", that is starts like:

Updating your yamls from Junifer v0.0.3:

If you use a BoldWarper, then now you need to change it to this: (code)
If you call function X with parameter y then you need to do it like this: (code)

Updating your yamls from Junifer v0.0.4:
...

and so on.

So if you had a Yaml that worked in v0.0.3 and now we are at v0.0.5, then you follow the two steps and you are done.

Originally posted by @fraimondo in https://github.com/juaml/junifer/issues/336#issuecomment-2085392654

> > We have a strict deprecation cycle! > > Gotta move fast 🏎️ > > > Anyways, let's force users to adapt. Maybe we can add a "deprecation" section on the DOCs? So users can somehow know easily how to adapt their old YAMLs? > > There is a dedicated section in the changelog docs. But after the examples are improved, should be straightforward for users to adapt. The changelogs have the information, but my take is that this is not enough. For me it happens that I might start working on a version that it does not even warns a deprecation and then update to a one that already removed the feature or changed the api. My idea was to create a "guide", that is starts like: Updating your yamls from Junifer v0.0.3: * If you use a BoldWarper, then now you need to change it to this: (code) * If you call function X with parameter y then you need to do it like this: (code) Updating your yamls from Junifer v0.0.4: ... and so on. So if you had a Yaml that worked in v0.0.3 and now we are at v0.0.5, then you follow the two steps and you are done. _Originally posted by @fraimondo in https://github.com/juaml/junifer/issues/336#issuecomment-2085392654_