search

input-output-hk / Developer-Experience-working-group

23 stars 15 forks source link

Channels for communicating major deprecation in cardano ecosystem libraries. #36

Open Benjmhart opened 2 years ago

Benjmhart commented 2 years ago

When Michael Peyton Jones attended the Working group meeting on Nov 1 to discuss future GHC support, the question was brought about communicating deprecations to users. Currently the IOG ecosystem (and the broader ecosystem as a whole) does not have a consistent system for communicating deprecations to developers either ahead of time or upon release.

After some high level research at options, I've arrived at the following suggestions

  1. Github releases for deprecations in the CURRENT commit (as MPJ suggested, they can be followed via RSS feeds)
  2. Pre-emptively creating a github issue to disclose the deprecation (and as a resource that can be linked directly from the below options)
  3. keep a section in the readme on upcoming major changes (with a link to the pre-emptive issue)
  4. DEPRECATED Pragmas (in the case of GHC support, this can be combined with CPP)

This would allow developers to be notified of the deprecation when looking through issues, at build time, or when investigating the repo directly, which is MUCH better than nothing, and i think all that could be asked.

I'd like to discuss this a bit more at the next Developer experience meeting, but this seems sound and reasonable to me.

Benjmhart commented 2 years ago

the goal here would be for this practice to be embraced across the cardano ecosystem, not just at IOG

zliu41 commented 2 years ago

Besides deprecations it would also be useful to standardize a way of marking certain APIs as beta.