haskell / haskell/hackage-server

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

Open
#1,037 0 comments 0 reactions 0 assignees View on GitHub
Dominant language
Haskell
Stars
467
Forks
225
PR merge metrics
No merged PRs in 30d

Description

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:
- #981
- #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.

Contributor guide

No contributing guide indexed for this repository

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.