From 0ea5240947a6e0f9c66c20c22afdc77fad5fa788 Mon Sep 17 00:00:00 2001
From: Artem Pelenitsyn <a.pelenitsyn@gmail.com>
Date: Sun, 24 Dec 2023 12:23:31 -0500
Subject: [PATCH] Add validate-revision workflow

It can be started manually to check that certain version bumps build fine.
It will ask to input an allow-newer line and a constraint line, which it
will add to the cabal.project file. For example: the "filepath"
allow-newer line and "filepath == 1.5" constraints line will make sure
that the build plan will have `filepath` at version 1.5.
---
 .github/workflows/validate.yml | 25 +++++++++++++++++++++++++
 CONTRIBUTING.md                | 32 ++++++++++++++++++++++++++++++++
 2 files changed, 57 insertions(+)

diff --git a/.github/workflows/validate.yml b/.github/workflows/validate.yml
index 5a30dfed233..d05e2a8e41b 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 1f313e3d43c..deb9b51cdf1 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 [![Open Source Helpers](https://www.codetriage.com/haskell/cabal/badges/users.svg)](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`.