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.