From 7457d2f6c75d5376c4e4015bcdecd50407f1956b Mon Sep 17 00:00:00 2001
From: Francesco Gazzetta <fgaz@fgaz.me>
Date: Mon, 31 May 2021 09:15:57 +0200
Subject: [PATCH] Explain why an older cabal-version is used

---
 doc/getting-started.rst | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/doc/getting-started.rst b/doc/getting-started.rst
index 565fdf6edb6..94167af3dba 100644
--- a/doc/getting-started.rst
+++ b/doc/getting-started.rst
@@ -35,6 +35,12 @@ Once you have an empty directory we can initialize our package:
 
     $ cabal init --cabal-version=2.4 --license=NONE -p myfirstapp
 
+.. note:: ``cabal-version`` refers to the
+          `version of the .cabal file format specification <file-format-changelog.html>`__,
+          that can be different from the versions of the cabal library and tool
+          in use. It is common to use a slightly older cabal-version, to strike
+          a compromise between feature availability and backward compatibility.
+
 This will generate the following files:
 
 .. code-block:: console