Deprecate Data.Text.IO.Utf8

Problem: text-2.1 has Data.Text.IO.Utf8 whose name conflicts with
our module with the same name.

Solution: our module contains 2 functions: `readFile` and `writeFile`.
They are implemented differently from `text` versions, but look
semantically equivalent. Our functions are also polymorphic in the
monad type, but that's orthogonal to the purpose of this package,
so we can sacrifice this polymorphism.
So it looks like our module doesn't add much value anymore and should
be deleted.
However, it's a good practice to deprecate something before deleting,
so we deprecate this module instead. It will be deleted in a future
version.
Note that the same module for lazy Text remains intact, since there
are apparently no such functions for lazy Text in text-2.1.

README.md

@@ -45,10 +45,12 @@ error due to encoding issues.
 If you are going to read a text file (to be precise, if you are going to open
 a file in text mode), you’ll probably use `withFile`, `openFile`, or `readFile`.
 Grab the first two from `System.IO.Utf8` or the latter from `Data.Text.IO.Utf8`.
+Starting from `text-2.1`, `Data.Text.IO.Utf8` is available in the `text` package
+itself, hence this module in `with-utf8` is now deprecated.
 
 _Note: it is best to import these modules qualified._
 
-_Note: there is no `System.IO.Utf8.readFile` because it’s 2020 and
+_Note: there is no `System.IO.Utf8.readFile` because it’s 2024 and
 you should not read `String`s from files._
 
 All these functions will make sure that the content will be treated as if it
@@ -72,6 +74,8 @@ doSomethingWithAFile h = Utf8.withhandle h $ do
 When writing a file either open it using `withFile`/`openFile` from
 `System.IO.Utf8` or write to it directly with `writeFile` from
 `Data.Text.IO.Utf8`.
+Starting from `text-2.1`, `Data.Text.IO.Utf8` is available in the `text` package
+itself, hence this module in `with-utf8` is now deprecated.
 
 _Note: it is best to import these modules qualified._
 

lib/Data/Text/IO/Utf8.hs

@@ -8,6 +8,7 @@
 -- Wrappers around simple file reading/writing functions from the
 -- @text@ package that reset the handle encoding to UTF-8.
 module Data.Text.IO.Utf8
+  {-# DEPRECATED "Use Data.Text.IO.Utf8 from the text package instead" #-}
   ( readFile
   , writeFile
   ) where

test/Test/Utf8/ReadWrite.hs

@@ -8,6 +8,10 @@
 {-# LANGUAGE PackageImports      #-}
 {-# LANGUAGE ScopedTypeVariables #-}
 
+-- Due to our Data.Text.IO.Utf8 which is deprecated and
+-- will be removed later.
+{-# OPTIONS_GHC -fno-warn-deprecations #-}
+
 module Test.Utf8.ReadWrite where
 
 import Control.DeepSeq (force)