Migration guide for haskell#10

guides/functor-combinator-instances-and-class1s.md

@@ -0,0 +1,80 @@
+# What
+
+CLC has approved the [proposal to relax instances for Functor combinators and put superclasses on \<class>1 to make less-breaking #10](https://github.com/haskell/core-libraries-committee/issues/10).
+This effectively means that the entirety of the class will now be exported from `Prelude`.
+
+Before, e.g.:
+```haskell
+instance (Eq1 f, Eq1 g, Eq a) => Eq (Compose f g a)
+
+class Eq1 f
+
+class Eq2 f
+```
+
+After, e.g.:
+```haskell
+instance Eq (f (g a)) => Eq (Compose f g a)
+
+class (forall a. Eq a => Eq (f a)) => Eq1 f
+
+class (forall a. Eq a => Eq1 (f a)) => Eq2 f
+```
+
+# When
+
+At the very earliest, the change may appear in GHC 9.6 (~ Q1 2023).
+
+# How
+
+This is a breaking change:
+
+1. People could define e.g. `Eq1` without `Eq`, or `Eq2` without `Eq1`
+
+2. People could write complicated instances on various abstract machinary that doesn't abide by the new superclasses.
+
+However, the breakage is of limited scope.
+An impact analysis (please see [comments following here](https://github.com/haskell/core-libraries-committee/issues/10#issuecomment-1166669613))
+showed that a only handle of packages that sucessfully pass dependency resolution on Stackage `nightly-2022-06-17` break with this change.
+Patches have been submitted to each of them.
+
+The migration policy for this change is backward-compatible: you can migrate already and still retain compatibility with existing GHCs.
+Because of this, CLC suggests applying patches at your earliest convenience.
+
+1. Add any missing instances
+
+2. Sadly there is no exact pattern for this, but here are two examples:
+
+   - https://github.com/haskell-streaming/streaming/pull/113
+   - https://github.com/RyanGlScott/text-show/pull/57
+
+   As one can see, this comes from rather fancy stuff.
+
+   `streaming` could be simpler, as the pre-existing comment points out, by just requiring a `Show1 f` constraint.
+   The other instance that required such a constraint did not need any migration.
+
+   `text-show` had `*1` instances that also converted between `String`- and `Text`-based showing.
+   This violates the superclass.
+   The instance must instead "pass through" `String`-based shows to `String`-based shows.
+
+# PR template
+
+Here is a template for (1), which you can use when raising PRs against affected libraries.
+
+> Title: Add instance _
+>
+> CLC has approved the proposal to add superclasses to `*1` and `*2`
+> classes
+> (https://github.com/haskell/core-libraries-committee/issues/10#). For
+> example, `forall a. Eq a => Eq (f a)` is now a superclass of `Eq1 f`.
+>
+> This means that you can not longer write a `*1` instance without its
+> regular class equivalent, and likewise a `*2` instances without its `*1`
+> equivalent.
+>
+> The implementation of the proposal is slated for GHC 9.6, but one can
+> already future-proof code to be compliant with this change in a
+> backwards-compatible way. No CPP required.
+>
+> Migration guide and more info:
+> https://github.com/haskell/core-libraries-committee/blob/main/guides/functor-combinator-instances-and-class1s.md