> 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@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@haskell.org
> http://mail.haskell.org/cgi-bin/mailman/listinfo/ghc-devs
_______________________________________________
ghc-devs mailing list
ghc-devs@haskell.org
http://mail.haskell.org/cgi-bin/mailman/listinfo/ghc-devs