Template Haskell stability

Sun Mar 10 20:40:47 UTC 2024

While having migration instructions is useful, not having to do anything is
even better.  I am already using `th-abstraction`, but I wish I didn't have
to use 2 libraries, that kind of do that same thing.  For the sake of
concreteness, consider how the type of `dataD` has evolved:

(2.3) dataD :: CxtQ -> Name -> [Name] -> [ConQ] -> [Name] -> DecQ
(2.4) dataD :: CxtQ -> Name -> [TyVarBndr] -> [ConQ] -> [Name] -> DecQ
(2.17) dataD :: Quote m => m Cxt -> Name -> [TyVarBndr ()] -> Maybe Kind ->
[m Con] -> [m DerivClause] -> m Dec

To find these changes I had to perform binary search on the versions on
`hackage`.

My suggestion would be to:

  1) Avoid such changes whenever possible.  For example:
    *  in 2.4 we could have kept the type signature of `dataD` as (it would
make a plain type binder), and added a new function `dataDTyVarBnd` for the
new behavior
    * In 2.17 We could have made a new type `TyVarBndrVis`, and made a type
synonym for `type TyVarBndr = TyVarBndrVis ()` to have the default
visibility that was there before the change.
  2) When we do need to make changes, we should annotate clearly when the
change happened in the haddocks, so that when we need to fix something in
the future, we minimize the amount of archeology that needs to be done.

On Sun, Mar 10, 2024 at 10:59 AM Oleg Grenrus <oleg.grenrus at iki.fi> wrote:

> > Another example of similar breakage was the changes to binders a little
> while ago.
>
> If you read GHC migration guide for 9.8 [1] (migration guides have been
> great resources, thanks to all their writers), it says
>
> > It is possible that Template Haskell code which compiled prior to GHC
> 9.8 will no longer compile after these changes. Here are some possible ways
> to make it compile with 9.8 in a backwards-compatible way, inspired by
> head.hackage!302 (merged):
>
> > * Construct TyVarBndrs using plainTV or kindedTV from
> Language.Haskell.TH.Lib, which is polymorphic over both TyVarBndr () and
> TyVarBndr BndrVis. These functions will default to using BndrReq on GHC 9.8.
> > * The th-abstraction [2] library provides a compatibility layer in the
> Language.Haskell.TH.Datatype.TyVarBndr module.
>
> [1]
> https://gitlab.haskell.org/ghc/ghc/-/wikis/migration/9.8#invisible-binders-in-type-level-declarations
> [2] https://hackage.haskell.org/package/th-abstraction
> In my personal opinion, the development of `template-haskell` hits the
> sweet spot of evolving (i.e. keeping up with GHC changes, and not
> stagnating), but being very reasonable in their breakages and also guiding
> how to migrate.
>
> Of course, the template-haskell library documentation could always be
> better, e.g. `TyVarBndr` docs could mention that things have changed and
> provide a link to migration guide;  tupE docs could mention existence of
> another variant and so on. However given that `template-haskell` doesn't
> really have an owner, and changes are mostly forced by changes in GHC, i'm
> very happy with what we have now. (In particular I hate the
> `template-haskell-internal` idea mentioned in
> https://gitlab.haskell.org/ghc/ghc/-/issues/24021; it won't help me with
> e.g. aeson but complicate contributing to GHC, lose-lose).
>
> That said, is it possible to setup the similar API change test for
> `template-haskell` as we have for `base`? I think it won't hurt, and may
> nudge contributors to document the changes.
>
> Cheers, Oleg
>
>
> On 10.3.2024 19.11, Iavor Diatchki wrote:
>
> Oh, that's really confusing, especially since the internal one is what
> shows up first when you search for stuff!
>
> Another example of similar breakage was the changes to binders a little
> while ago.
>
> On Sun, Mar 10, 2024 at 10:02 AM Oleg Grenrus <oleg.grenrus at iki.fi> wrote:
>
>>  > So what do I do?
>>
>> There are two tupE functions.
>>
>> In Language.Haskell.TH.Lib.Internal module the type has changed. That's
>> the module used by GHC itself, to represent quotations. As the module
>> documentation says
>>
>>  > Language.Haskell.TH.Lib.Internal exposes some additional
>> functionality that is used internally in GHC's integration with Template
>> Haskell. This is not a part of the public API, and as such, there are no
>> API guarantees for this module from version to version.
>>
>> In the Language.Haskell.TH.Lib module which is documented as
>>
>>  > Language.Haskell.TH.Lib contains lots of useful helper functions for
>> generating and manipulating Template Haskell terms
>>
>> the type of tupE [1] has been left unchanged, and it's still
>>
>>     tupE :: Quote m => [m Exp] -> m Exp
>>
>> [1]
>>
>> https://hackage.haskell.org/package/template-haskell-2.21.0.0/docs/Language-Haskell-TH-Lib.html#v:tupE
>>
>> ---
>>
>> Oleg
>>
>>
>> On 10.3.2024 18.56, Iavor Diatchki wrote:
>> > Hello,
>> >
>> > I am not sure if this is the right list to post to, but I suspect
>> > template-haskell is mostly modified by GHC folk, which is why I chose
>> > to post here, and there is no maintainer listed, based just the
>> > `libraries` list.
>> >
>> > Template Haskell is a very useful tool, but I am always quite wary of
>> > using it, because it is so unstable.   I understand the need to change
>> > the syntax, as the language evolves, but I feel that changes are made
>> > without any consideration for backward compatibility, which is very
>> > unfortunate.
>> >
>> > To give you an example, I am currently using GHC 9.6.4, and I am
>> > working on a small TH utility.  I need to make a tuple expression, but
>> > of a dynamic size, so I can't use the special syntax, and need to use
>> > a function to do so.  So I am using the function, `tupE`, which has
>> > the following type:
>> >
>> >     tupE :: Quote m => [m Exp] -> m Exp
>> >
>> > This is quite nice and unsurprising.   When I look oh `hackage`,
>> > however, the type of this function has changed, now it is:
>> >
>> >    tupE :: Quote m => [m (Maybe Exp)] -> m Expr
>> >
>> > So what do I do?  Basically I should not use this function, because as
>> > soon as I upgrade the compiler everything will break!  Furthermore
>> > there is no documentation at all to explain what this function is
>> > supposed to do (I can't fathom why it is taking `Maybe` as arguments),
>> > or when it changed, etc.
>> >
>> > So my plea would be---change the syntax at will, but let's try to keep
>> > the convenience functions that build the syntax stable: instead of
>> > changing functions, it is just as easy to add a new function.  I
>> > understand that sometimes things need to change, but then we should
>> > describe what changed, and in which versions.   I don't think these
>> > are hard things to do, and I really think it will have great benefit
>> > to everyone using TH.
>> >
>> > Cheers,
>> > -Iavor
>> >
>> >
>> >
>> >
>> >
>> >
>> >
>> >
>> > _______________________________________________
>> > ghc-devs mailing list
>> > ghc-devs at haskell.org
>> > http://mail.haskell.org/cgi-bin/mailman/listinfo/ghc-devs
>> _______________________________________________
>> ghc-devs mailing list
>> ghc-devs at haskell.org
>> http://mail.haskell.org/cgi-bin/mailman/listinfo/ghc-devs
>>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.haskell.org/pipermail/ghc-devs/attachments/20240310/9f7f73d2/attachment.html>