Build/test not run when documentation is uploaded via cabal upload -d

[andreasabel]

I learned from @gbaz that the package build on hackage server is not run when the user uploads the documentation self, using cabal upload -d.
However, the cabal docs do not hint at that:

Usage: cabal upload [FLAGS] TARFILES
...
 -d, --documentation            Upload documentation instead of a source
                                package. By default, this uploads
                                documentation for a package candidate. To
                                upload documentation for a published package,
                                combine with --publish.

Also, this behavior is unexpected. The stomach feeling "unexpected" can in this case precisely pinned to the absence of two mathematical properties:

1. Monotonicity: You put more in, you get more out. So, if I provide more data to Hackage, I expect to get better service, not worse.
2. Orthogonality: Hackage does not keep the two dimensions documentation and build/tests separate, but moving to the right on the first dimension moves me automatically back on the other dimension. (Trivium: In the 2006 edition of the ICFP Programming Contest, the CMU team devised a non-orthogonal programming language "Balance" which makes it utmost hard to even implement simple operations like addition: https://kilthub.cmu.edu/articles/journal_contribution/The_Cult_of_the_Bound_Variable_The_9th_Annual_ICFP_Programming_Contest/6610520).

Ironically, the current behavior provides an equally unexpected "solution" to the problem of failing tests:

• Allow maintainers to opt-out of tests #981
• Tests for doctest fail #991

Uploading the documentation (quickly enough) will stifle the build/test runner, and no banners will be created.

But seriously, I think uploading the documentation should not prevent Hackage to build the documentation itself. I always thought of the uploaded documentation to just be a placeholder for the "officially" built one, as a safeguard:

• The uploaded documentation will be used as long as the builder has not run.
• The uploaded documentation will be used in case the doc build failed.

In the other cases, the officially built docs should be used.