<div dir="ltr">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:<br><br>(2.3) dataD :: CxtQ -> Name -> [Name] -> [ConQ] -> [Name] -> DecQ<br>(2.4) dataD :: CxtQ -> Name -> [TyVarBndr] -> [ConQ] -> [Name] -> DecQ<br>(2.17) dataD :: Quote m => m Cxt -> Name -> [TyVarBndr ()] -> Maybe Kind -> [m Con] -> [m DerivClause] -> m Dec<div><br></div><div>To find these changes I had to perform binary search on the versions on `hackage`.</div><div><br></div><div>My suggestion would be to:</div><div><br></div><div> 1) Avoid such changes whenever possible. For example:</div><div> * 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</div><div> * 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.</div><div> 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.</div><br><div><br></div><div><br></div><div><br></div><div><br></div><div><br></div><div><br></div><div><br></div><div><br></div></div><br><div class="gmail_quote"><div dir="ltr" class="gmail_attr">On Sun, Mar 10, 2024 at 10:59 AM Oleg Grenrus <<a href="mailto:oleg.grenrus@iki.fi">oleg.grenrus@iki.fi</a>> wrote:<br></div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">
<div>
<p>> Another example of similar breakage was the changes to
binders a little while ago.<br>
<br>
If you read GHC migration guide for 9.8 [1] (migration guides have
been great resources, thanks to all their writers), it says<br>
<br>
> 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):<br>
<br>
> * 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.<br>
> * The th-abstraction [2] library provides a compatibility
layer in the Language.Haskell.TH.Datatype.TyVarBndr module.<br>
<br>
[1]
<a href="https://gitlab.haskell.org/ghc/ghc/-/wikis/migration/9.8#invisible-binders-in-type-level-declarations" target="_blank">https://gitlab.haskell.org/ghc/ghc/-/wikis/migration/9.8#invisible-binders-in-type-level-declarations</a><br>
[2] <a href="https://hackage.haskell.org/package/th-abstraction" target="_blank">https://hackage.haskell.org/package/th-abstraction</a><br>
</p>
<div>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.<br>
<br>
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 <a href="https://gitlab.haskell.org/ghc/ghc/-/issues/24021" target="_blank">https://gitlab.haskell.org/ghc/ghc/-/issues/24021</a>; it
won't help me with e.g. aeson but complicate contributing to GHC,
lose-lose).<br>
<br>
</div>
<div>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.<br>
<br>
Cheers, Oleg<br>
<br>
<br>
On 10.3.2024 19.11, Iavor Diatchki wrote:<br>
</div>
<blockquote type="cite">
<div dir="ltr">
<div>Oh, that's really confusing, especially since the internal
one is what shows up first when you search for stuff!</div>
<div><br>
</div>
<div>Another example of similar breakage was the changes to
binders a little while ago.<br>
</div>
</div>
<br>
<div class="gmail_quote">
<div dir="ltr" class="gmail_attr">On Sun, Mar 10, 2024 at
10:02 AM Oleg Grenrus <<a href="mailto:oleg.grenrus@iki.fi" target="_blank">oleg.grenrus@iki.fi</a>>
wrote:<br>
</div>
<blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex"> >
So what do I do?<br>
<br>
There are two tupE functions.<br>
<br>
In Language.Haskell.TH.Lib.Internal module the type has
changed. That's <br>
the module used by GHC itself, to represent quotations. As the
module <br>
documentation says<br>
<br>
> Language.Haskell.TH.Lib.Internal exposes some additional
<br>
functionality that is used internally in GHC's integration
with Template <br>
Haskell. This is not a part of the public API, and as such,
there are no <br>
API guarantees for this module from version to version.<br>
<br>
In the Language.Haskell.TH.Lib module which is documented as<br>
<br>
> Language.Haskell.TH.Lib contains lots of useful helper
functions for <br>
generating and manipulating Template Haskell terms<br>
<br>
the type of tupE [1] has been left unchanged, and it's still<br>
<br>
tupE :: Quote m => [m Exp] -> m Exp<br>
<br>
[1] <br>
<a href="https://hackage.haskell.org/package/template-haskell-2.21.0.0/docs/Language-Haskell-TH-Lib.html#v:tupE" rel="noreferrer" target="_blank">https://hackage.haskell.org/package/template-haskell-2.21.0.0/docs/Language-Haskell-TH-Lib.html#v:tupE</a><br>
<br>
---<br>
<br>
Oleg<br>
<br>
<br>
On 10.3.2024 18.56, Iavor Diatchki wrote:<br>
> Hello,<br>
><br>
> I am not sure if this is the right list to post to, but I
suspect <br>
> template-haskell is mostly modified by GHC folk, which is
why I chose <br>
> to post here, and there is no maintainer listed, based
just the <br>
> `libraries` list.<br>
><br>
> Template Haskell is a very useful tool, but I am always
quite wary of <br>
> using it, because it is so unstable. I understand the
need to change <br>
> the syntax, as the language evolves, but I feel that
changes are made <br>
> without any consideration for backward compatibility,
which is very <br>
> unfortunate.<br>
><br>
> To give you an example, I am currently using GHC 9.6.4,
and I am <br>
> working on a small TH utility. I need to make a tuple
expression, but <br>
> of a dynamic size, so I can't use the special syntax, and
need to use <br>
> a function to do so. So I am using the function, `tupE`,
which has <br>
> the following type:<br>
><br>
> tupE :: Quote m => [m Exp] -> m Exp<br>
><br>
> This is quite nice and unsurprising. When I look oh
`hackage`, <br>
> however, the type of this function has changed, now it
is:<br>
><br>
> tupE :: Quote m => [m (Maybe Exp)] -> m Expr<br>
><br>
> So what do I do? Basically I should not use this
function, because as <br>
> soon as I upgrade the compiler everything will break!
Furthermore <br>
> there is no documentation at all to explain what this
function is <br>
> supposed to do (I can't fathom why it is taking `Maybe`
as arguments), <br>
> or when it changed, etc.<br>
><br>
> So my plea would be---change the syntax at will, but
let's try to keep <br>
> the convenience functions that build the syntax stable:
instead of <br>
> changing functions, it is just as easy to add a new
function. I <br>
> understand that sometimes things need to change, but then
we should <br>
> describe what changed, and in which versions. I don't
think these <br>
> are hard things to do, and I really think it will have
great benefit <br>
> to everyone using TH.<br>
><br>
> Cheers,<br>
> -Iavor<br>
><br>
><br>
><br>
><br>
><br>
><br>
><br>
><br>
> _______________________________________________<br>
> ghc-devs mailing list<br>
> <a href="mailto:ghc-devs@haskell.org" target="_blank">ghc-devs@haskell.org</a><br>
> <a href="http://mail.haskell.org/cgi-bin/mailman/listinfo/ghc-devs" rel="noreferrer" target="_blank">http://mail.haskell.org/cgi-bin/mailman/listinfo/ghc-devs</a><br>
_______________________________________________<br>
ghc-devs mailing list<br>
<a href="mailto:ghc-devs@haskell.org" target="_blank">ghc-devs@haskell.org</a><br>
<a href="http://mail.haskell.org/cgi-bin/mailman/listinfo/ghc-devs" rel="noreferrer" target="_blank">http://mail.haskell.org/cgi-bin/mailman/listinfo/ghc-devs</a><br>
</blockquote>
</div>
</blockquote>
</div>
</blockquote></div>