Dealing with interface deprecation

Dealing with interface deprecation

[Ludovic Courtès]

Hello Guix!

In Guix, configuration is code, which is great!  But that also means
users occasionally have to deal with things like “API deprecation”,
which never sounds exciting, especially when all you want is to get your
system upgraded Right Now.

So I think it’s important to be very careful in how we deal with API
deprecation, in particular in Guix System (and in Guix Home once we’ve
removed the “technology preview” label).

There were two examples where, with my “regular user” hat on (which I
particularly enjoy), I got deprecation messages that were not actionable
for me because they lacked source location info.  This was addressed by
these changes:

  https://git.savannah.gnu.org/cgit/guix.git/commit?id=e0bd47b4fd5eb009f34004242e16b976e58756b0
  https://git.savannah.gnu.org/cgit/guix.git/commit?id=baf4272df2350a40bfa198f5cdb42e707e32ad71

As you can see, providing good actionable messages for record field
deprecation is a bit of a craft, but hopefully that gives an idea of how
to get there; maybe we’ll eventually come up with a high-level way to
express that.

Packages may also be part of the “API”.  On ‘core-updates’, several TeX
Live packages were deprecated but still used because there wasn’t any
warning.  This is how I addressed it:

  https://git.savannah.gnu.org/cgit/guix.git/commit?id=3dc8052b51241fe7857059d3300dad3a0f9f68fd

Thoughts?  Tips and tricks?

Ludo’.

Re: Dealing with interface deprecation

[Maxim Cournoyer]

Hello!

Ludovic Courtès <ludo@gnu.org> writes:

> Hello Guix!
>
> In Guix, configuration is code, which is great!  But that also means
> users occasionally have to deal with things like “API deprecation”,
> which never sounds exciting, especially when all you want is to get your
> system upgraded Right Now.
>
> So I think it’s important to be very careful in how we deal with API
> deprecation, in particular in Guix System (and in Guix Home once we’ve
> removed the “technology preview” label).
>
> There were two examples where, with my “regular user” hat on (which I
> particularly enjoy), I got deprecation messages that were not actionable
> for me because they lacked source location info.  This was addressed by
> these changes:
>
>   https://git.savannah.gnu.org/cgit/guix.git/commit?id=e0bd47b4fd5eb009f34004242e16b976e58756b0
>   https://git.savannah.gnu.org/cgit/guix.git/commit?id=baf4272df2350a40bfa198f5cdb42e707e32ad71
>
> As you can see, providing good actionable messages for record field
> deprecation is a bit of a craft, but hopefully that gives an idea of how
> to get there; maybe we’ll eventually come up with a high-level way to
> express that.
>
> Packages may also be part of the “API”.  On ‘core-updates’, several TeX
> Live packages were deprecated but still used because there wasn’t any
> warning.  This is how I addressed it:
>
>   https://git.savannah.gnu.org/cgit/guix.git/commit?id=3dc8052b51241fe7857059d3300dad3a0f9f68fd
>
> Thoughts?  Tips and tricks?

Wow!  Thanks a lot for sharing these tips on the art of making better
deprecation!  I'll keep these commits bookmarked for the next time :-).

Maxim