Skip to content

Cabal Packages Hackage Revision Policy

Jump to bottom
Mikolaj Konarski edited this page Feb 20, 2024 · 6 revisions

This document has been originally created at https://github.com/haskell/cabal/issues/9531#issuecomment-1866930240 and in the fortnightly cabal devs meetings. The cabal wiki is the new authoritative location for the document. Please don't edit it in a major way without first discussing the changes on the Matrix channel and the devs meeting.

Version 1.0 of Cabal Packages Hackage Revision Policy

tl;dr

  1. revisions are good
  2. only for the newest published cabal version
  3. merged PR first
  4. build and test locally (but ideally in CI)
  5. leeway for exceptional circumstances

Full text:

  1. We are lax with respect to cabal package revisions on Hackage. Any minor or major benefit (e.g., less build plans failing) is enough to justify applying any relaxation or restriction of bounds that matches reality.
  2. By default, we only accept revision change requests for the newest minor version of the newest major version of cabal on Hackage.
  3. The crucial pre-requisite we expect from a person requesting a revision is a PR modifying the deps merged to the branch that (loosely) corresponds to the revised cabal version (e.g., the common release branch for the whole major version).
  4. The secondary pre-requisite is a local build (one architecture and one GHC version) of all cabal packages and a local cabal-testuite run (as described in https://github.com/haskell/cabal/blob/master/cabal-testsuite/README.md) that shows no regressions and where --with-cabal is pointing to the just built cabal binary (loosely) corresponding to the state after revision. Ideally, the whole cabal CI matrix of tests would be run in a dedicated new PR (afterwards closed and preserved) that adds constraints and --allow-newer to force the dependency versions of interest.
  5. Exceptional circumstances may waive any of the above, in particular it may sometimes be prudent to revise before the pre-requisites are met. Transparency and paper trail are especially important in such cases (publicly state and document each decision, ask for objections).

Edit: Addendum for old cabal versions:

  1. Ideally, we'd have one PR per cabal version affected, with full testing, etc., see above. This is, however, not possible when CI is dead on the particular release branch and bringing CI back to life is unlikely to be worthwhile.
  2. For older cabal versions, in particular those with unmaintained release branches, we still welcome and encourage a PR to the relevant release branch. Upon merging, it would ensure the version bounds on the branch match the version bounds as revised Hackage. If possible, the CI would show the new bounds build fine, even if tests fail due to CI bit-rot. If CI can't show a successful build (and the build errors don't point to an actual problem with the proposed new bounds), a local build reported in the PR, with or without a local test run, would be a help to reviewers and the PR can be merged manually regardless of CI.
  3. For really old versions or when the release branch is out of sync with Hackage already, we welcome Hackage trustees and cabal maintainers to scale back the level of formality accordingly. We certainly don't expect bringing the bounds on a long-abandoned branch back in sync with Haskell. A ping on the Matrix channel wouldn't hurt in any case, so that we are aware which branches are out of sync (possibly by accident) and, generally, to share the hacking joy and gratitude for anybody that cares about cabal.

Related tools and discussions

Clone this wiki locally