From 318e921fe2461c264234b22900c902dac28a138b Mon Sep 17 00:00:00 2001
From: Javier Sagredo <jasataco@gmail.com>
Date: Tue, 12 Nov 2024 09:06:01 +0100
Subject: [PATCH] Warn on cabal format invocation

---
 cabal-install/src/Distribution/Client/Main.hs |  2 ++
 changelog.d/pr-10549                          | 11 +++++++++++
 2 files changed, 13 insertions(+)
 create mode 100644 changelog.d/pr-10549

diff --git a/cabal-install/src/Distribution/Client/Main.hs b/cabal-install/src/Distribution/Client/Main.hs
index e6278a5ef9a..a3ebcc4e4c5 100644
--- a/cabal-install/src/Distribution/Client/Main.hs
+++ b/cabal-install/src/Distribution/Client/Main.hs
@@ -236,6 +236,7 @@ import Distribution.Simple.Utils
   , notice
   , topHandler
   , tryFindPackageDesc
+  , warn
   )
 import Distribution.Text
   ( display
@@ -1343,6 +1344,7 @@ checkAction checkFlags extraArgs _globalFlags = do
 formatAction :: Flag Verbosity -> [String] -> Action
 formatAction verbosityFlag extraArgs _globalFlags = do
   let verbosity = fromFlag verbosityFlag
+  warn verbosity "This command is not a full formatter yet"
   path <- case extraArgs of
     [] -> relativeSymbolicPath <$> tryFindPackageDesc verbosity Nothing
     (p : _) -> return $ makeSymbolicPath p
diff --git a/changelog.d/pr-10549 b/changelog.d/pr-10549
new file mode 100644
index 00000000000..257fc103197
--- /dev/null
+++ b/changelog.d/pr-10549
@@ -0,0 +1,11 @@
+synopsis: Warn on `cabal format`
+packages: cabal-install
+prs: #10549
+issues:
+significance:
+
+description: {
+
+- Despite its name, `cabal format` is not a proper formatter for cabal files. By chance users have sometimes found the command eventhough it is not mentioned in the help text, and they used it to format cabal files. This has some downsides like comments are stripped away or common stanzas are inlined, the command is more like a dump of the resolved package description. There are future plans (#7544) to make it an actual formatter so, rather than going through a deprecation cycle, we decided to keep this command for future use and in the meantime just warn the user about the fact that it is not a proper formatter.
+
+}