diff --git a/.github/workflows/validate.yml b/.github/workflows/validate.yml index 5a30dfed23377f6bc1c61538ff7f60f807df5520..d05e2a8e41bddbd2e25b9c3a5b43dce44a025ff5 100644 --- a/.github/workflows/validate.yml +++ b/.github/workflows/validate.yml @@ -30,6 +30,19 @@ on: release: types: - created + workflow_call: + + # See https://github.com/haskell/cabal/blob/master/CONTRIBUTING.md#hackage-revisions + workflow_dispatch: + inputs: + allow-newer: + description: allow-newer line + required: true + type: string + constraints: + description: constraints line + required: true + type: string env: # We choose a stable ghc version across all os's @@ -40,6 +53,11 @@ env: GHC_FOR_COMPLETE_HACKAGE_TESTS: '9.2.8' COMMON_FLAGS: '-j 2 -v' + # See https://github.com/haskell/cabal/blob/master/CONTRIBUTING.md#hackage-revisions + ALLOWNEWER: ${{ github.event.inputs.allow-newer }} + CONSTRAINTS: ${{ github.event.inputs.constraints }} + + jobs: validate: name: Validate ${{ matrix.os }} ghc-${{ matrix.ghc }} @@ -68,6 +86,13 @@ jobs: - uses: actions/checkout@v4 + # See https://github.com/haskell/cabal/blob/master/CONTRIBUTING.md#hackage-revisions + - name: Manually supplied constraints/allow-newer + if: ${{ github.event_name == 'workflow_dispatch' }} + run: | + echo 'allow-newer:' ${ALLOWNEWER} >> cabal.project.validate + echo 'constraints:' ${CONSTRAINTS} >> cabal.project.validate + # See the following link for a breakdown of the following step # https://github.com/haskell/actions/issues/7#issuecomment-745697160 - uses: actions/cache@v3 diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 1f313e3d43cd71e8d2d76920532e3936a8a16840..deb9b51cdf11a0f1e28ced45b503de656c5ca479 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -345,3 +345,35 @@ Auto-generated API documentation for the `master` branch of Cabal is automatical ## Issue triage [](https://www.codetriage.com/haskell/cabal) You can contribute by triaging issues which may include reproducing bug reports or asking for vital information, such as version numbers or reproduction instructions. If you would like to start triaging issues, one easy way to get started is to [subscribe to cabal on CodeTriage](https://www.codetriage.com/haskell/cabal). + +Hackage Revisions +----------------- + +We are reactive rather than proactive with revising bounds on our dependencies +for code already released on Hackage. If you would benefit from a version bump, +please, open a ticket and get familiar with +[our revision policy](https://github.com/haskell/cabal/issues/9531#issuecomment-1866930240). + +The burden of proof that the bump is harmless remains with you, but we have a CI +setup to show that our main pipeline ("Validate") is fine with the bump. To use +it, someone with enough permissions needs to go on the +[Validate workflow page](https://github.com/haskell/cabal/actions/workflows/validate.yml) +and dispatch it manually by clicking "Run workflow". + +Running workflow manually as discussed above requires you to supply two inputs: + +> allow-newer line +> constraints line + +Going via an example, imagine that Cabal only allows `tar` or version less then +or equal to 0.6, and you want to bump it to 0.6. Then, to show that Validate +succeeds with `tar` 0.6, you should input + +- `tar` to the "allow-newer line" +- `tar ==0.6` to the "constraints line" + +Hopefully, running the Validate pipeline with these inputs succeeds and you +supply the link to the run in the ticket about bumping the bound and making a revision. + +If interested in technical details, refer to the parts of `validate.yml` that +mention `hackage-revisions`.