Update the 0.9.0 upgrade guide

Add more details about re-creating the older stream types.

docs/User/Project/Upgrading-0.8-to-0.9.md

@@ -1,9 +1,9 @@
 # Upgrading to streamly 0.9.0
 
-Also see:
+Also see the detailed changelog describing all the changes in the release:
 
 * [0.9.0 API Changelog](/docs/User/ProjectRelated/ApiChangelogs/0.8.3-0.9.0.txt) or
-  https://hackage.haskell.org/package/streamly-0.9.0/docs/docs/User/ProjectRelated/ApiChangelogs/0.8.3-0.9.0.txt
+* [0.9.0 API Changelog](https://hackage.haskell.org/package/streamly-0.9.0/docs/docs/User/ProjectRelated/ApiChangelogs/0.8.3-0.9.0.txt)
 
 `Streamly.Prelude` module has been deprecated, equivalent
 functionality is covered by the `Streamly.Data.Stream`,
@@ -46,13 +46,14 @@ Assume the following imports in the code snippets below:
 
 ## Dependencies in cabal file
 
-If you allow streamly < 0.9 in version bounds then you may not be able
-to build if you:
+If you allow streamly < 0.9 in version bounds in your package then you
+may not be able to build if any of the following is true:
 
-* also depend on the new `streamly-core` package (module name conflicts)
-* depend on `streamly-bytestring` >= 0.2 (type conflict)
+* there is a dependency on `streamly-core` (module name conflicts)
+* there is a dependency on `streamly-bytestring` >= 0.2 (type conflict)
 
-You can use a build flag to allow older streamly versions:
+You can define and use a build flag in your package to allow older
+streamly versions:
 
 ```
 flag old-streamly
@@ -103,6 +104,82 @@ ZipSerialM or WSerialT) with custom Applicative or Monadic properties.
 But in general, try to avoid specific types and use explicit functions
 from the stream module.
 
+Here are the TH macro based recipes to define types equivalent to all the older
+types:
+
+```
+{-# LANGUAGE StandaloneDeriving #-}
+{-# LANGUAGE TemplateHaskell #-}
+{-# LANGUAGE TypeFamilies #-}
+{-# LANGUAGE UndecidableInstances #-}
+
+import Streamly.Data.Stream.MkType
+import qualified Streamly.Data.Stream.Prelude as Stream
+import qualified Streamly.Internal.Data.StreamK as StreamK
+import Language.Haskell.TH
+```
+
+`SerialT`: Use `CrossStreamK` from `Streamly.Internal.Data.StreamK` equivalent
+Monad and other instances.
+
+For `WSerialT`, create a newtype wrapper using the following monad bind
+operation:
+
+```
+bind = StreamK.bindWith StreamK.interleave
+```
+
+`WSerialT` requires `StreamK`, therefore you can not generate the code directly
+using TH macros. However, you can print the code generated by the TH macro.
+Then you can tweak that code, replacing `Stream` type with `StreamK`.
+
+```
+expr <- runQ (mkCrossType "WSerialT" "bind" True)
+putStrLn $ pprint expr
+```
+
+For `AsyncT`:
+
+```
+bind = flip (Stream.parConcatMap id)
+$(mkCrossType "AsyncT" "bind" True)
+```
+
+For `WAsyncT`:
+
+```
+bind = flip (Stream.parConcatMap (Stream.interleaved True))
+$(mkCrossType "WAsyncT" "bind" True)
+```
+
+For `AheadT`:
+
+```
+bind = flip (Stream.parConcatMap (Stream.ordered True))
+$(mkCrossType "AheadT" "bind" True)
+```
+
+For `ParallelT`:
+
+```
+bind = flip (Stream.parConcatMap (Stream.eager True))
+$(mkCrossType "ParallelT" "bind" True)
+```
+
+For `ZipSerialM`:
+
+```
+apply = Stream.zipWith ($)
+$(mkZipType "ZipSerialM" "apply" False)
+```
+
+For `ZipAsync`:
+
+```
+apply = Stream.parApply id
+$(mkZipType "ZipAsync" "apply" False)
+```
+
 `adapt` is not needed anymore.
 
 ```haskell docspec
@@ -228,7 +305,8 @@ combinators are prefixed with `par`.
 Parallel combinators take a concurrency config argument to specify the
 concurrency control parameters.  The following combinators have the same
 meaning as before except that they are used to set the config parameters
-instead of being applied on the stream.
+instead of being applied on the stream:
+
 * `rate`
 * `maxRate`
 * `constRate`

streamly.cabal

@@ -167,6 +167,7 @@ extra-doc-files:
     docs/User/Explanatory/*.md
     docs/User/Explanatory/streaming-pradigms.rst
     docs/User/Project/*.md
+    docs/User/Project/Upgrading-0.8-to-0.9.md
     docs/User/Project/*.link
     docs/User/Project/ApiChangelogs/0.8.3-0.9.0.txt
     docs/User/Project/ApiChangelogs/0.8.3.txt