Unbreak cookbooks and tutorial (Mono or multi repo?)

[akhesaCaro]

Some cookbooks have been forsaken for many years now. I think it is very important to bring them back to life for the community.

I can't do it yet, for some of them, without breaking the CI.

Here are the external servant packages on which the cookbooks/tutorial depend on :

• servant-quickcheck
• servant-auth
• servant-multipart
• servant-swagger
• servant-blaze
• servant-js

2 options are in front of us :

Mono repo

To avoid dependency loops (like this), It think it would be nice to bring the packages back into the main servant repository.

Pros

• Direct feedback on any change in servant, we would be forced to keep documentation up-to-date.

Cons

• The cookbooks need to be compatible with ghc 8.0.2 (no DerivingStrategies, DerivingVia, import Data.Semigroup to have the (<>) operator is mandatory, etc.), which could lead to more verbosity. It could also be seen as a pro: they would always be compatible with the advertised compatible GHC versions of servant.
• Potentially longer CI time.

Cookbooks and tutorial in their own repo

We could put the cookbooks and tutorial in their own repo and pin the packages they depend on.

Pros

• The cookbooks could have different versions depending on the version of the packages they are using.
• Potentially shorter CI time

Cons

• So far, the tendency has been to comment out the cookbooks if the package they rely on is not compatible with a new PR. If they are in their own repo, far away from our heart, we would probably forget them.
• If I see that servant is compatible with GHC 8.0.2, I would probably assume that the every coobooks would be compatible with it?

---*-

IMHO, the mono repository solution is better. What do you think?

[arianvp]

The cookbooks need to be compatible with ghc 8.0.2 (no DerivingStrategies, DerivingVia, import Data.Semigroup to have the (<>) operator is mandatory, etc.), which could lead to more verbosity.

Haskell-ci respected the Tested-With field in the cabal file so that certain cabal files were only run against the supported GHC versions.

We could add that behaviour to the GitHub-actions based CI as well perhaps. Cookbooks were never meant to be built against all supported GHC versions.

[gdeest]

We could add that behaviour to the GitHub-actions based CI as well perhaps. Cookbooks were never meant to be built against all supported GHC versions.

That's definitely possible. What's the rationale for it though ? I'd argue that it could be quite surprising for new users that copy-pasting code from the cookbooks doesn't work, even though servant core libraries do build.

[arianvp]

I think cookbooks shouldn't be limited to the lowest common denominator. e.g. I don't see why a cookbook wouldn't be allowed use DerivingVia or TypeApplications eventhough the servant core code does not use those language extensions. For example some part of UVerb ergonomics (deriving HasStatus via WithStatus 200) is nice to demonstrate in a cookbook.

[gdeest]

Fair point 👍

I'll re-introduce those usages and exclude those cookbooks from being tested with lower versions of GHC. I'll probably add some comment in the cookbooks themselves to mention which minimal version of GHC they rely on.

[akhesaCaro]

@arianvp , look at this : #1407 so we can keep the DerinvingVia.

Did you have time to give some thoughts on the mono repo VS multi repo matter?

[arianvp]

If we can keep the cookbooks using newer features; then Mono-repo seems the easiest road to success to me!