poor ergonomics of Cabal version mismatch errors

Describe the bug cabal-install does a very poor job of communicating that it does not handle older cabal packages that are assumed to be for cabal-install 1.x.

To Reproduce Steps to reproduce the behavior:

Given the minimal cabal file

name:           cabaltest
version:        0.1.0.0

and cabal-install 3.4, the result is

$ cabal build
Resolving dependencies...
cabal: Could not resolve dependencies:
[__0] trying: cabaltest-0.1.0.0 (user goal)
[__1] next goal: cabaltest:setup.Cabal (dependency of cabaltest)
[__1] rejecting: cabaltest:setup.Cabal-3.4.0.0/installed-3.4.0.0 (conflict: cabaltest => cabaltest:setup.Cabal>=1.0 && <1.25)
(…)

I used the un-versioned build command because this is about what a newcomer to cabal will see. Discussion from IRC follows.

Expected behavior A newcomer to the Haskell ecosystem will not know that this is not expected to work, and will in particular be confused by the above version mismatch caused by absence of a cabal-version field in the cabal file.

$ cabal build
Warning: the file "cabaltest.cabal" lacks a "Cabal-version" field. This usually indicates a package intended for
cabal-install 1.24 or earlier, which is unlikely to build with modern cabal-install. Please add a "Cabal-version"
field or use an earlier version of cabal-install to build it.

Additional context

[06 16:22:41] <gurkenglas> I appear to have gotten myself into a pickle. I have a directory "cabaltest" containing only cabaltest.cabal with contents: https://bpa.st/QFLQ
[06 16:23:15] <gurkenglas> running cabal build gets me: https://bpa.st/4GJA
[06 16:25:58] <geekosaur> a cabal file without a cabal-version field is assumed to be cabal v1
[06 16:26:36] <geekosaur> (cabal library that is)
[06 16:26:58] <gurkenglas> ah. how silly of me to think that starting from an empty slate would get comprehensible errors :P
[06 16:27:31] <geekosaur> empty slate is `cabal init`
[06 16:28:21] <geekosaur> problem is there are still a lot of cabal v1 files floating around that don't declare themselves as such, so cabal-install has to assume any cabal file that doesn't say otherwise is one of them
[06 16:29:00] <geekosaur> because cabal v2+ are very different from cabal v1
[06 16:29:38] <gurkenglas> geekosaur: shouldn't it be able to notice from looking at "rejecting: test:setup.Cabal-3.4.0.0/installed-3.4.0.0 (conflict: test => test:setup.Cabal>=1.0 && <1.25)" that this is not what's happening, though?
[06 16:30:10] <geekosaur> `test:setup.Cabal>=1.0 && <1.25` is precisely that happening
[06 16:30:59] <geekosaur> it inserts that dependency because it sees what it thinks is a cabal v1 file
[06 16:31:19] <gurkenglas> misunderstanding? i mean: shouldn't it notice from the conflict with 3.4 that the file is probably not intended as v1?
[06 16:31:46] <geekosaur> no, because people quite often try to build cabal v1 packages with later cabal versions
[06 16:34:07] <gurkenglas> ah so that error line expects the user to read it as: "i am rejecting this because you're apparently trying to use Cabal 3.4 to build a Cabal 1.0 project. No can do. Downgrade your cabal installation or change the cabal-version in *.cabal"?
[06 16:34:40] <geekosaur> yes
[06 16:35:05] <geekosaur> it'd be nice if cabal reported this better, admittedly
[06 16:35:24] <geekosaur> it's almost as bad reporting "this package requires a different version of ghc"
[06 16:36:19] <Hecate> hello
[06 16:36:28] <Hecate> are we talking about ergonomics in haskell tooling?
[06 16:36:33] <geekosaur> yep
[06 16:36:50] <geekosaur> cabal error messages have long been frustrating
[06 16:36:55] <Hecate> indeed they have
[06 16:37:01] <Hecate> we can fix this
[06 16:37:40] <Hecate> geekosaur: would you mind creating a ticket for this ergonomics problem?
[06 16:41:38] <geekosaur> creating

Something similar happens with ghc/base package mismatches: the user has to know to look for requires installed instance in the dependency traceback. I expect that one is harder to fix, though, because cabal probably shouldn't know that a version mismatch on base means the wrong version of ghc is being used (especially if the new split-base proposal goes through).

Hécate asked me to report this, as indicated at the end of the IRC snippet.

haskell / cabal

poor ergonomics of Cabal version mismatch errors #8626