Set up a mechanism to collaborate with users of the GHC API
Currently, users of the GHC API need to discover on their own what has changed during GHC releases, and then figure out how to upgrade.
This issue is about defining a protocol for users of the GHC API and GHC developers to exchange the necessary information to upgrade to later compiler versions.
The issue is motivated in this issue in the Liquid Haskell repo, and in the talk Integrating Liquid Haskell with GHC at HIW23.
In essence, users of the GHC API could provide concisely their expectations about the GHC API. They must list all the definitions they use from the GHC API, and they must supply tests that show how they expect definitions to behave when they are not stable. GHC developers can then comment on how to migrate to using more appropriate definitions either by inspecting this materials in advance, or upon discovering that some internal change in GHC has broken the tests.
I propose to have testsuites in the GHC repo for each GHC API client that is interested in receiving feedback from the GHC developers. When these testsuites fail, the GHC developers can comment out the offending code, and leave comments explaining how to update the code. The users of the GHC API can then use these comments to update their clients. Here's my first attempt of a note for the Liquid Haskell testsuite:
{-
Note [Liquid Haskell testsuite for the GHC API]
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
This testsuite tests the GHC API as used by Liquid Haskell.
The main purpose of this testsuite is to inform the Liquid Haskell
developers about how to update the plugin after breaking changes in the
GHC API. The definitions exported by "Liquid.GHC.API" are used by Liquid
Haskell, even if no test uses them here.
When these tests break, please feel free to patch the source code by
commenting out the offending tests or imports in this testsuite. The
Liquid Haskell developers will appreciate any accompanying comments
explaining how to replace the GHC API definitions that have been removed
or changed. The comments are to be read by persons who are no GHC
experts.
When Liquid Haskell needs are not clear enough to discuss remedies, just
leave a comment asking for clarification. This might include requests for
additional documentation for the tests or the need to export a definition
in "Liquid.GHC.API".
If you feel adventurous, the Liquid Haskell team will be deeply thankful
if you consider contributing fixes to this testsuite as well.
-}
Perhaps the users of the GHC API can set themselves as code owners of the given testsuites, so they receive notifications when modifications to the testsuite are made.
I'd like to collect suggestions for this proposal, get a testsuite merged for Liquid Haskell (as in !11454 (closed)), and then document this somewhere GHC developers consider appropriate: maybe the wiki (please, feel free to suggest locations), or the ghc users guide.