Strategy to deprecate API

[moreal]

In my thought, there are some command line args or GraphQL fields, else something to deprecate. But we remain it for backward compatibility. If we remove it, it will be broken. But I think it limits the code to be better. So we MUST have a strategy to deprecate API.

• [ ] Who are the users?
• [ ] How to notify the deprecation plan?
• [ ] How to guide the migration?

You can reference the below items:

• https://kubernetes.io/docs/reference/using-api/deprecation-policy/#deprecating-a-flag-or-cli
• https://docs.github.com/en/graphql/overview/breaking-changes

[moreal]

Just my thought notes:

Q. Who are users?

• planetarium/9c-launcher developers.
• Node operators using planetarium/NineChronicles.Headless.
• Nine Chronicles Ecosystem developers using GraphQL APIs.

Q. How to notify the deprecation plan?

To deprecate some CLI commands or some GraphQL APIs, it should have a plan for when the API will be removed.

In the GitHub GraphQL API Breaking Changes case, it shows when to remove the APIs with descriptions. Users should keep an eye out for the breaking changes page. I wonder how it is possible to make users keep eye on the page 🤔

In Kubernetes CLI, it shows the warning message when the API will be deprecated. Though it seems like the message came from its server, I like this way because the user will see the message while using the app (CLI).

So I think:

• Make a Breaking Changes page and record every deprecation plan one by one.
• Gain users from the 9c community (Discord server) and make them know the site.
• PR it in several ways when new breaking changes are posted:
  • 9c Discord Server
  • NineChronicles.Headless' documentation site
  • Developer portal
  • RSS
  • Blog

[moreal]

In this comment, I want to start discussion about break changes from dependencies. At the Libplanet.Explorer case (i.e. query.chainQuery), it breaks its backward compatibility because it doesn't have a duty to guarantee backward compatibility (0.. release). But if we should guarantee backward compatibility, we should have a rule about backward incompatibiilty from submodules' changes.