Re: Template Haskell stability

* 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 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 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-i... [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 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-...

---

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

_______________________________________________ ghc-devs mailing list ghc-devs@haskell.org http://mail.haskell.org/cgi-bin/mailman/listinfo/ghc-devs