juaml / juaml/junifer

[DOC]: Add migration guide for YAMLs

Open
#338 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
Python
Stars
16
Forks
13
Avg merge
10h 20m
Merged PRs (30d)
1

Description

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

Contributor guide

No contributing guide indexed for this repository

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with the dedicated changelog documentation and the examples referenced in the issue, then collect the YAML changes across Junifer versions. Add a version-by-version migration guide with the old and updated forms, so users upgrading from an older YAML can follow each required step.

Written by the indexing model from the issue text.

Assessment

Tech stack
yaml
Domain
documentation
Issue type
Documentation
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.