ModMenu icon indicating copy to clipboard operation
ModMenu copied to clipboard

Provide clear instructions for devs to update deprecated features and fix warnings

Open MestreLion opened this issue 4 years ago • 0 comments

This is related to #231 and several other related requests regarding API changes and deprecations.

Currently we have this scenario:

  • ModMenu introduces a new feature / API change.
  • The old API is marked deprecated and a WARNING is emitted, saying "ask the author of this mod to support the new API"
  • Users see the warnings and promptly ask authors to fix
  • Many authors resist to fix, for several reasons:
    • They don't know how to fix
    • Don't have the time/willingness to study the new API and update
    • "If ain't broke I don't care", or "That's ModMenu's fault for constantly changing the API"
  • Users start complaining with ModMenu, creating issues and requesting warnings to be disabled, grouped, etc

ModMenu could minimize or even solve all this by making it dead easy to update to the new API. For Authors, and even users to submit a PR.

In every deprecation Warning, add a link to a wiki page that explains that exact change and precisely what needs to be done to update. So users can ask authors: "Could you please support the new API by following the instructions here?". Or better: "Here's a PR that implements the changes described at ...". That's much better than a "please fix this" request that demands authors to take their time.

Example: the infamous modmenu:clientsideOnly' custom value deprecation warning.

How to fix it? Where to fix it? Should I just remove that block/line, or are there additional changes required? The wiki only gives subtle clues:

There are more badges, such as the Client badge, but this is automatically determined by the environment defined in the official fabric.mod.json metadata

Oh, ok, so we need to edit fabric.mod.json. Cool. So we do as #300 did and remove the custom block. But... what about this "determined by the environment"? How/Where do I set this? Where is this documented? Wiki does not mention it. Granted, this is a general Fabric setting, not part of the ModMenu API. But still, more research is needed to make sure we set environment to client (is that a plain key-value? A new group? In the same file?)

See the problem?

Please, if you guys want new API to be supported, without adding tension between users and authors, for every deprecation warning create a Wiki page instructing exactly where and what should be changed. Add code snippets for the common cases. Lower the barrier for adoption as low as you possibly can.

MestreLion avatar Nov 13 '21 21:11 MestreLion