Add a README to the files generated by cabal init

cabal-install/src/Distribution/Client/Init/Defaults.hs

@@ -23,6 +23,7 @@ module Distribution.Client.Init.Defaults
   , defaultLicenseIds
   , defaultMainIs
   , defaultChangelog
+  , defaultReadme
   , defaultCategories
   , defaultInitFlags
   , defaultLanguage
@@ -75,6 +76,9 @@ defaultPackageType = Executable
 defaultChangelog :: FilePath
 defaultChangelog = "CHANGELOG.md"
 
+defaultReadme :: FilePath
+defaultReadme = "README.md"
+
 defaultLicense :: CabalSpecVersion -> SpecLicense
 defaultLicense csv
   | csv < CabalSpecV2_2 = SpecLicense $ Right AllRightsReserved

cabal-install/src/Distribution/Client/Init/FileCreators.hs

@@ -18,6 +18,7 @@ module Distribution.Client.Init.FileCreators
   ( -- * Commands
     writeProject
   , writeLicense
+  , writeReadme
   , writeChangeLog
   , prepareLibTarget
   , prepareExeTarget
@@ -70,6 +71,7 @@ writeProject (ProjectSettings opts pkgDesc libTarget exeTarget testTarget)
 
       writeLicense opts pkgDesc
       writeChangeLog opts pkgDesc
+      writeReadme opts pkgDesc
 
       let pkgFields = mkPkgDescription opts pkgDesc
           commonStanza = mkCommonStanza opts
@@ -240,6 +242,28 @@ writeChangeLog opts pkgDesc
     go =
       void $ writeFileSafe opts defaultChangelog changeLog
 
+writeReadme :: Interactive m => WriteOpts -> PkgDescription -> m ()
+writeReadme opts pkgDesc
+  | Just docs <- _pkgExtraDocFiles pkgDesc
+  , defaultReadme `Set.member` docs =
+      go
+  | defaultReadme `elem` _pkgExtraSrcFiles pkgDesc = go
+  | otherwise = return ()
+  where
+    readme =
+      unlines
+        [ "# " ++ prettyShow (_pkgName pkgDesc)
+        , ""
+        , "## Build"
+        , ""
+        , "Run `$ cabal build` to build the project"
+        , "## Documentation"
+        , ""
+        , "Run `$ cabal haddock --open` to generate a reference for the API of the project."
+        ]
+    go =
+      void $ writeFileSafe opts defaultReadme readme
+
 -- -------------------------------------------------------------------- --
 -- Utilities
 

cabal-install/src/Distribution/Client/Init/FlagExtractors.hs

@@ -138,7 +138,7 @@ getExtraDocFiles :: Interactive m => InitFlags -> m (Maybe (Set String))
 getExtraDocFiles =
   pure
     . Just
-    . flagElim (Set.singleton defaultChangelog) Set.fromList
+    . flagElim (Set.fromList [defaultChangelog, defaultReadme]) Set.fromList
     . extraDoc
 
 -- | Ask whether the project builds a library or executable.

cabal-install/src/Distribution/Client/Init/NonInteractive/Heuristics.hs

@@ -101,7 +101,7 @@ guessExtraDocFiles flags = do
   return $
     Just $
       if null extraDocs
-        then Set.singleton defaultChangelog
+        then Set.fromList [defaultChangelog, defaultReadme]
         else Set.fromList extraDocs
 
 -- | Try to guess the package type from the files in the package directory,

cabal-install/src/Distribution/Client/Init/Simple.hs

@@ -112,7 +112,7 @@ createProject v pkgIx _srcDb initFlags = do
 genSimplePkgDesc :: Interactive m => InitFlags -> m PkgDescription
 genSimplePkgDesc flags = mkPkgDesc <$> currentDirPkgName
   where
-    defaultExtraDoc = Just $ Set.singleton defaultChangelog
+    defaultExtraDoc = Just $ Set.fromList [defaultChangelog, defaultReadme]
 
     extractExtraDoc [] = defaultExtraDoc
     extractExtraDoc fs = Just $ Set.fromList fs

cabal-install/tests/UnitTests/Distribution/Client/Init/Interactive.hs

@@ -96,7 +96,7 @@ createProjectTest pkgIx srcDb =
                 _pkgSynopsis desc @?= "We are Qux, and this is our package"
                 _pkgCategory desc @?= "Control"
                 _pkgExtraSrcFiles desc @?= mempty
-                _pkgExtraDocFiles desc @?= pure (Set.singleton "CHANGELOG.md")
+                _pkgExtraDocFiles desc @?= pure (Set.fromList ["CHANGELOG.md", "README.md"])
 
                 _libSourceDirs lib @?= ["quxSrc"]
                 _libLanguage lib @?= Haskell98
@@ -206,7 +206,7 @@ createProjectTest pkgIx srcDb =
                 _pkgSynopsis desc @?= "Qux's package"
                 _pkgCategory desc @?= "Control"
                 _pkgExtraSrcFiles desc @?= mempty
-                _pkgExtraDocFiles desc @?= pure (Set.singleton "CHANGELOG.md")
+                _pkgExtraDocFiles desc @?= pure (Set.fromList ["CHANGELOG.md", "README.md"])
 
                 _libSourceDirs lib @?= ["src"]
                 _libLanguage lib @?= Haskell98
@@ -306,7 +306,7 @@ createProjectTest pkgIx srcDb =
                 _pkgSynopsis desc @?= "Qux's package"
                 _pkgCategory desc @?= "Control"
                 _pkgExtraSrcFiles desc @?= mempty
-                _pkgExtraDocFiles desc @?= pure (Set.singleton "CHANGELOG.md")
+                _pkgExtraDocFiles desc @?= pure (Set.fromList ["CHANGELOG.md", "README.md"])
 
                 _libSourceDirs lib @?= ["src"]
                 _libLanguage lib @?= Haskell98
@@ -392,7 +392,7 @@ createProjectTest pkgIx srcDb =
                 _pkgSynopsis desc @?= "Qux's package"
                 _pkgCategory desc @?= "Control"
                 _pkgExtraSrcFiles desc @?= mempty
-                _pkgExtraDocFiles desc @?= pure (Set.singleton "CHANGELOG.md")
+                _pkgExtraDocFiles desc @?= pure (Set.fromList ["CHANGELOG.md", "README.md"])
 
                 _testMainIs test @?= HsFilePath "Main.hs" Standard
                 _testDirs test @?= ["test"]
@@ -480,7 +480,7 @@ createProjectTest pkgIx srcDb =
                 _pkgSynopsis desc @?= "Qux's package"
                 _pkgCategory desc @?= "Control"
                 _pkgExtraSrcFiles desc @?= mempty
-                _pkgExtraDocFiles desc @?= pure (Set.singleton "CHANGELOG.md")
+                _pkgExtraDocFiles desc @?= pure (Set.fromList ["CHANGELOG.md", "README.md"])
 
                 _libSourceDirs lib @?= ["src"]
                 _libLanguage lib @?= Haskell98
@@ -566,7 +566,7 @@ createProjectTest pkgIx srcDb =
                 _pkgSynopsis desc @?= "Qux's package"
                 _pkgCategory desc @?= "Control"
                 _pkgExtraSrcFiles desc @?= mempty
-                _pkgExtraDocFiles desc @?= pure (Set.singleton "CHANGELOG.md")
+                _pkgExtraDocFiles desc @?= pure (Set.fromList ["CHANGELOG.md", "README.md"])
 
                 _libSourceDirs lib @?= ["src"]
                 _libLanguage lib @?= Haskell98
@@ -627,7 +627,7 @@ createProjectTest pkgIx srcDb =
                 flags =
                   emptyFlags
                     { cabalVersion = Flag CabalSpecV1_10
-                    , extraDoc = Flag [defaultChangelog]
+                    , extraDoc = Flag [defaultChangelog, defaultReadme]
                     , extraSrc = Flag ["README.md"]
                     }
 
@@ -650,7 +650,7 @@ createProjectTest pkgIx srcDb =
                 _pkgHomePage desc @?= "qux.com"
                 _pkgSynopsis desc @?= "Qux's package"
                 _pkgCategory desc @?= "Control"
-                _pkgExtraSrcFiles desc @?= Set.fromList [defaultChangelog, "README.md"]
+                _pkgExtraSrcFiles desc @?= Set.fromList [defaultChangelog, defaultReadme]
                 _pkgExtraDocFiles desc @?= Nothing
 
                 _libSourceDirs lib @?= ["src"]
@@ -729,7 +729,7 @@ createProjectTest pkgIx srcDb =
                 _pkgSynopsis desc @?= "Qux's package"
                 _pkgCategory desc @?= "Control"
                 _pkgExtraSrcFiles desc @?= mempty
-                _pkgExtraDocFiles desc @?= pure (Set.singleton "CHANGELOG.md")
+                _pkgExtraDocFiles desc @?= pure (Set.fromList ["CHANGELOG.md", "README.md"])
 
                 _exeMainIs exe @?= HsFilePath "Main.hs" Standard
                 _exeApplicationDirs exe @?= ["exe"]

cabal-install/tests/UnitTests/Distribution/Client/Init/NonInteractive.hs

@@ -113,7 +113,7 @@ driverFunctionTest pkgIx srcDb comp =
                 _pkgSynopsis desc @?= "We are Qux, and this is our package"
                 _pkgCategory desc @?= "Control"
                 _pkgExtraSrcFiles desc @?= mempty
-                _pkgExtraDocFiles desc @?= pure (Set.singleton "CHANGELOG.md")
+                _pkgExtraDocFiles desc @?= pure (Set.fromList ["CHANGELOG.md", "README.md"])
 
                 _libSourceDirs lib @?= ["quxSrc"]
                 _libLanguage lib @?= Haskell98
@@ -200,7 +200,7 @@ driverFunctionTest pkgIx srcDb comp =
                 _pkgSynopsis desc @?= "We are Qux, and this is our package"
                 _pkgCategory desc @?= "Control"
                 _pkgExtraSrcFiles desc @?= mempty
-                _pkgExtraDocFiles desc @?= pure (Set.singleton "CHANGELOG.md")
+                _pkgExtraDocFiles desc @?= pure (Set.fromList ["CHANGELOG.md", "README.md"])
 
                 _libSourceDirs lib @?= ["quxSrc"]
                 _libLanguage lib @?= Haskell98
@@ -388,7 +388,7 @@ driverFunctionTest pkgIx srcDb comp =
                 _pkgSynopsis desc @?= ""
                 _pkgCategory desc @?= ""
                 _pkgExtraSrcFiles desc @?= mempty
-                _pkgExtraDocFiles desc @?= pure (Set.singleton "CHANGELOG.md")
+                _pkgExtraDocFiles desc @?= pure (Set.fromList ["CHANGELOG.md", "README.md"])
 
                 _libSourceDirs lib @?= ["src"]
                 _libLanguage lib @?= Haskell2010
@@ -540,7 +540,7 @@ driverFunctionTest pkgIx srcDb comp =
                 _pkgSynopsis desc @?= ""
                 _pkgCategory desc @?= ""
                 _pkgExtraSrcFiles desc @?= mempty
-                _pkgExtraDocFiles desc @?= pure (Set.singleton "CHANGELOG.md")
+                _pkgExtraDocFiles desc @?= pure (Set.fromList ["CHANGELOG.md", "README.md"])
 
                 _libSourceDirs lib @?= ["src"]
                 _libLanguage lib @?= Haskell2010
@@ -684,7 +684,7 @@ driverFunctionTest pkgIx srcDb comp =
                 _pkgSynopsis desc @?= ""
                 _pkgCategory desc @?= ""
                 _pkgExtraSrcFiles desc @?= mempty
-                _pkgExtraDocFiles desc @?= pure (Set.singleton "CHANGELOG.md")
+                _pkgExtraDocFiles desc @?= pure (Set.fromList ["CHANGELOG.md", "README.md"])
 
                 _libSourceDirs lib @?= ["src"]
                 _libLanguage lib @?= Haskell2010
@@ -794,7 +794,7 @@ driverFunctionTest pkgIx srcDb comp =
                 _pkgSynopsis desc @?= ""
                 _pkgCategory desc @?= ""
                 _pkgExtraSrcFiles desc @?= mempty
-                _pkgExtraDocFiles desc @?= pure (Set.singleton "CHANGELOG.md")
+                _pkgExtraDocFiles desc @?= pure (Set.fromList ["CHANGELOG.md", "README.md"])
 
                 _libSourceDirs lib @?= ["src"]
                 _libLanguage lib @?= Haskell2010
@@ -885,7 +885,7 @@ driverFunctionTest pkgIx srcDb comp =
                 _pkgSynopsis desc @?= ""
                 _pkgCategory desc @?= ""
                 _pkgExtraSrcFiles desc @?= mempty
-                _pkgExtraDocFiles desc @?= pure (Set.singleton "CHANGELOG.md")
+                _pkgExtraDocFiles desc @?= pure (Set.fromList ["CHANGELOG.md", "README.md"])
 
                 _exeMainIs exe @?= HsFilePath "Main.hs" Standard
                 _exeApplicationDirs exe @?= ["app"]
@@ -1190,14 +1190,14 @@ nonInteractiveTests pkgIx srcDb comp =
             [ testSimple
                 "No extra sources"
                 extraDocFileHeuristics
-                (pure (Set.singleton "CHANGELOG.md"))
+                (pure (Set.fromList ["CHANGELOG.md", "README.md"]))
                 [ "test-package"
                 , "[]"
                 ]
             , testSimple
                 "Extra doc files present"
                 extraDocFileHeuristics
-                (pure $ Set.singleton "README.md")
+                (pure $ Set.fromList ["CHANGELOG.md", "README.md"])
                 [ "test-package"
                 , "[\"README.md\"]"
                 ]

cabal-install/tests/UnitTests/Distribution/Client/Init/Simple.hs

@@ -168,7 +168,7 @@ simplePkgDesc pkgName =
     ""
     ""
     mempty
-    (Just $ Set.singleton defaultChangelog)
+    (Just $ Set.fromList [defaultReadme, defaultChangelog])
 
 simpleLibTarget :: [Dependency] -> LibTarget
 simpleLibTarget baseDep =

changelog.d/pr-11260

@@ -0,0 +1,4 @@
+synopsis: Add a README to the files generated by cabal init
+packages: cabal-install
+prs: #11260
+issues: #11231