Document requirement to run stack --upgrade-cabal

[conklech]

General summary/comments

See #2795; this issue is essentially a reframing of that issue as a documentation issue.

Stack will happily build packages using a different version of the Cabal library than GHC's, causing a custom Setup.hs to fail. This can be resolved by running stack --upgrade-cabal.

The requirement to run stack --upgrade-cabal, which appears to have been in place for a few months now, should be documented; if possible within stack itself.

Steps to reproduce

See #2795.

Expected

Either successful building, or a warning/error that the wrong version of Cabal is installed.

Actual

See #2795.

Stack version

$ stack --version
Version 1.3.2, Git revision 3f675146590da4f3edf768b89355f798229da2a5 (4395 commits) x86_64 hpack-0.15.0

Method of installation

Official binary, downloaded from this repository; stack setup.

[decentral1se]

@conklech if you could check out my changes from #2970 and test them, that would be great. Is your environment still in this state? You'll need to compile Stack from sources:

$ git clone git@github.com:commercialhaskell/stack.git stack && cd $_
$ git fetch origin pull/2970/head:"pr_2970" && git checkout pr_2970
$ stack install
$ ~/.local/bin/stack build # in your project

[conklech]

Confirm that with #2970 I get the message Cabal version mismatch detected. Try running 'stack setup --upgrade-cabal' at the beginning of the build.

However, for some reason on Windows the build succeeds nonetheless; i.e. the underlying issue #2795 doesn't seem to manifest on Windows, at least with LTS-7.15. I don't know why.

(The underlying issue still shows up on MacOS, but I can't build @lwm's patch on my MacOS system due to #2577.)

[decentral1se]

Thanks for the update nonetheless!