Template Haskell stability

[Simon Peyton Jones]

>
>     *  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


Iavor, what about *pattern matching *on DataD?   Or don't you do that?

If we exclude pattern matching on TH syntax, it becomes much more feasible
to make a stable API.  Is that a goal worth seeking?  Would it help a few
people?  A lot of people?

Simon

On Sun, 10 Mar 2024 at 20:41, Iavor Diatchki <iavor.diatchki at gmail.com>
wrote:

> 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
>>>
>> _______________________________________________
> 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/20240311/20e3c690/attachment-0001.html>