Merge branch 'master' into fix9151

.github/pull_request_template.md

@@ -10,8 +10,7 @@ Include the following checklist in your PR:
 * [ ] Any changes that could be relevant to users [have been recorded in the changelog](https://github.com/haskell/cabal/blob/master/CONTRIBUTING.md#changelog).
 * [ ] The documentation has been updated, if necessary.
 * [ ] [Manual QA notes](https://github.com/haskell/cabal/blob/master/CONTRIBUTING.md#qa-notes) have been included.
-
-Bonus points for added automated tests!
+* [ ] Tests have been added. (*Ask for help if you don’t know how to write them! Ask for an exemption if tests are too complex for too little coverage!*)
 
 ---
 

.github/workflows/bootstrap.skip.yml

@@ -0,0 +1,39 @@
+name: Bootstrap Skip
+
+# This Workflow is special and contains a workaround for a known limitation of GitHub CI.
+#
+# The problem: We don't want to run the "bootstrap" jobs on PRs which contain only changes
+# to the docs, since these jobs take a long time to complete without providing any benefit.
+# We therefore use path-filtering in the workflow triggers for the bootstrap jobs, namely
+# "paths-ignore: doc/**". But the "Bootstrap post job" is a required job, therefore a PR cannot
+# be merged unless the "Bootstrap post job" completes succesfully, which it doesn't do if we 
+# filter it out.
+#
+# The solution: We use a second job with the same name which always returns the exit code 0.
+# The logic implemented for "required" workflows accepts if 1) at least one job with that name
+# runs through, AND 2) If multiple jobs of that name exist, then all jobs of that name have to
+# finish successfully.
+on:
+  push:
+    paths:
+      - 'doc/**'
+      - '**/README.md'
+      - 'CONTRIBUTING.md'
+    branches:
+      - master
+  pull_request:
+    paths:
+      - 'doc/**'
+      - '**/README.md'
+      - 'CONTRIBUTING.md'
+  release:
+    types:
+      - created
+
+jobs:
+  bootstrap-post-job:
+    if: always()
+    name: Bootstrap post job
+    runs-on: ubuntu-latest
+    steps:
+      - run: exit 0

.github/workflows/bootstrap.yml

@@ -5,11 +5,22 @@ concurrency:
   group: ${{ github.ref }}-${{ github.workflow }}
   cancel-in-progress: true
 
+# Note: This workflow file contains the required job "Bootstrap post job". We are using path filtering
+# here to ignore PRs which only change documentation. This can cause a problem, see the workflow file
+# "bootstrap.skip.yml" for a description of the problem and the solution provided in that file.
 on:
   push:
+    paths-ignore:
+      - 'doc/**'
+      - '**/README.md'
+      - 'CONTRIBUTING.md'
     branches:
       - master
   pull_request:
+    paths-ignore:
+      - 'doc/**'
+      - '**/README.md'
+      - 'CONTRIBUTING.md'
   release:
     types:
       - created
@@ -66,3 +77,20 @@ jobs:
         with:
           name: cabal-${{ matrix.os }}-${{ matrix.ghc }}-bootstrapped
           path: _build/artifacts/*
+
+  # We use this job as a summary of the workflow
+  # It will fail if any of the previous jobs does it
+  # This way we can use it exclusively in branch protection rules
+  # and abstract away the concrete jobs of the workflow, including their names
+  bootstrap-post-job:
+    if: always()
+    name: Bootstrap post job
+    runs-on: ubuntu-latest
+    # IMPORTANT! Any job added to the workflow should be added here too
+    needs: [bootstrap]
+
+    steps:
+      - run: |
+          echo "jobs info: ${{ toJSON(needs) }}"
+      - if: contains(needs.*.result, 'failure') || contains(needs.*.result, 'cancelled')
+        run: exit 1

.github/workflows/format.yml

@@ -10,8 +10,9 @@ jobs:
     runs-on: ubuntu-latest
     steps:
     - uses: actions/checkout@v4
-    - uses: haskell-actions/run-fourmolu@v8
+    - uses: haskell-actions/run-fourmolu@v9
       with:
+        version: "0.12.0.0"
         pattern: |
           Cabal/**/*.hs
           Cabal-syntax/**/*.hs

.github/workflows/lint.yml

@@ -9,10 +9,10 @@ jobs:
     runs-on: ubuntu-latest
     steps:
     - uses: actions/checkout@v4
-    - uses: haskell/actions/hlint-setup@v2
+    - uses: haskell-actions/hlint-setup@v2
       with:
         version: "3.5"
-    - uses: haskell/actions/hlint-run@v2
+    - uses: haskell-actions/hlint-run@v2
       with:
         path: "."
-        fail-on: suggestion
+        fail-on: suggestion

.github/workflows/validate.skip.yml

@@ -0,0 +1,39 @@
+name: Validate Skip
+
+# This Workflow is special and contains a workaround for a known limitation of GitHub CI.
+#
+# The problem: We don't want to run the "validate" jobs on PRs which contain only changes
+# to the docs, since these jobs take a long time to complete without providing any benefit.
+# We therefore use path-filtering in the workflow triggers for the validate jobs, namely
+# "paths-ignore: doc/**". But the "Validate post job" is a required job, therefore a PR cannot
+# be merged unless the "Validate post job" completes succesfully, which it doesn't do if we 
+# filter it out.
+#
+# The solution: We use a second job with the same name which always returns the exit code 0.
+# The logic implemented for "required" workflows accepts if 1) at least one job with that name
+# runs through, AND 2) If multiple jobs of that name exist, then all jobs of that name have to
+# finish successfully.
+on:
+  push:
+    paths:
+      - 'doc/**'
+      - '**/README.md'
+      - 'CONTRIBUTING.md'
+    branches:
+      - master
+  pull_request:
+    paths:
+      - 'doc/**'
+      - '**/README.md'
+      - 'CONTRIBUTING.md'
+  release:
+    types:
+      - created
+
+jobs:
+  validate-post-job:
+    if: always()
+    name: Validate post job
+    runs-on: ubuntu-latest
+    steps:
+      - run: exit 0

.github/workflows/validate.yml

@@ -11,22 +11,33 @@ concurrency:
   group: ${{ github.ref }}-${{ github.workflow }}
   cancel-in-progress: true
 
+# Note: This workflow file contains the required job "Validate post job". We are using path filtering
+# here to ignore PRs which only change documentation. This can cause a problem, see the workflow file
+# "validate.skip.yml" for a description of the problem and the solution provided in that file.
 on:
   push:
+    paths-ignore:
+      - 'doc/**'
+      - '**/README.md'
+      - 'CONTRIBUTING.md'
     branches:
       - master
   pull_request:
+    paths-ignore:
+      - 'doc/**'
+      - '**/README.md'
+      - 'CONTRIBUTING.md'
   release:
     types:
       - created
 
 env:
   # We choose a stable ghc version across all os's
   # which will be used to do the next release
-  GHC_FOR_RELEASE: '9.2.7'
+  GHC_FOR_RELEASE: '9.2.8'
   # Ideally we should use the version about to be released for hackage tests and benchmarks
-  GHC_FOR_SOLVER_BENCHMARKS: '9.2.7'
-  GHC_FOR_COMPLETE_HACKAGE_TESTS: '9.2.7'
+  GHC_FOR_SOLVER_BENCHMARKS: '9.2.8'
+  GHC_FOR_COMPLETE_HACKAGE_TESTS: '9.2.8'
   COMMON_FLAGS: '-j 2 -v'
 
 jobs:
@@ -38,7 +49,7 @@ jobs:
     strategy:
       matrix:
         os: ["ubuntu-latest", "macos-latest", "windows-latest"]
-        ghc: ["9.6.1", "9.4.4", "9.2.7", "9.0.2", "8.10.7", "8.8.4", "8.6.5", "8.4.4"]
+        ghc: ["9.6.3", "9.4.7", "9.2.8", "9.0.2", "8.10.7", "8.8.4", "8.6.5", "8.4.4"]
         exclude:
           # corrupts GHA cache or the fabric of reality itself, see https://github.com/haskell/cabal/issues/8356
           - os: "windows-latest"
@@ -107,7 +118,7 @@ jobs:
           echo "FLAGS=$FLAGS" >> $GITHUB_ENV
 
       - name: Allow newer dependencies when built with latest GHC
-        if: ${{ matrix.ghc }} == '9.6.1'
+        if: ${{ matrix.ghc }} == '9.6.3'
         run: |
           echo "allow-newer: rere:base, rere:transformers" >> cabal.project.validate
 
@@ -161,15 +172,13 @@ jobs:
         # Have to disable *-suite validation:
         # - the [email protected] problem is tracked at https://github.com/haskell/cabal/issues/8858
         # - but curently can't run it with GHC 9.6, tracking: https://github.com/haskell/cabal/issues/8883
-        if: (runner.os != 'Windows')  || (matrix.ghc != '9.6.1')
         run: sh validate.sh $FLAGS -s lib-suite
 
       - name: Validate cli-tests
         run: sh validate.sh $FLAGS -s cli-tests
 
       - name: Validate cli-suite
         # Have to disable *-suite validation, see above the comment for lib-suite
-        if: (runner.os != 'Windows')  || (matrix.ghc != '9.6.1')
         run: sh validate.sh $FLAGS -s cli-suite
 
   validate-old-ghcs:

.gitignore

@@ -73,6 +73,8 @@ cabal-testsuite/**/haddocks
 # python artifacts from documentation builds
 *.pyc
 .python-sphinx-virtualenv/
+venv
+.venv
 /doc/.skjold_cache/
 
 # macOS folder metadata
@@ -83,3 +85,6 @@ bench.html
 
 # Emacs
 .projectile
+
+# I'm unsure how to ignore these generated golden files
+cabal-testsuite/PackageTests/NewUpdate/RejectFutureIndexStates/cabal.out

.hlint.yaml

@@ -94,9 +94,10 @@
 - ignore: {name: "Use when"} # 1 hint
 
 - arguments:
+    - --ignore-glob=Cabal-syntax/src/Distribution/Fields/Lexer.hs
     - --ignore-glob=cabal-testsuite/PackageTests/CmmSources/src/Demo.hs
     - --ignore-glob=cabal-testsuite/PackageTests/CmmSourcesDyn/src/Demo.hs
-    - --ignore-glob=Cabal-syntax/src/Distribution/Fields/Lexer.hs
+    - --ignore-glob=cabal-testsuite/PackageTests/CmmSourcesExe/src/Demo.hs
     - --ignore-glob=templates/Paths_pkg.template.hs
     - --ignore-glob=templates/SPDX.LicenseExceptionId.template.hs
     - --ignore-glob=templates/SPDX.LicenseId.template.hs

CONTRIBUTING.md

@@ -38,20 +38,26 @@ cabal build cabal-tests # etc...
 Running tests
 -------------
 
-**Using Github Actions.**
+**Using GitHub Actions.**
 If you are not in a hurry, the most convenient way to run tests on Cabal
 is to make a branch on GitHub and then open a pull request; our
-continuous integration service on Github Actions builds and
+continuous integration service on GitHub Actions builds and
 tests your code.  Title your PR with WIP so we know that it does not need
 code review.
 
-Some tips for using Github Actions effectively:
+Some tips for using GitHub Actions effectively:
 
-* Github Actions builds take a long time.  Use them when you are pretty
+* GitHub Actions builds take a long time.  Use them when you are pretty
   sure everything is OK; otherwise, try to run relevant tests locally
   first.
 
-* Watch over your jobs on the [Github Actions website](http://github.org/haskell/cabal/actions).
+* If you are only changing documentation in the `docs/` subdirectory,
+  or if you change `README.md` or `CONTRIBUTING.md`, then we only run a
+  small subset of the CI jobs. You can therefore open small PRs with
+  improvements to the documentation without feeling guilty about wasted
+  resources!
+
+* Watch over your jobs on the [GitHub Actions website](http://github.org/haskell/cabal/actions).
   If you know a build of yours is going to fail (because one job has
   already failed), be nice to others and cancel the rest of the jobs,
   so that other commits on the build queue can be processed.
@@ -75,9 +81,9 @@ failures:
    a specific operating system?  If so, try reproducing the
    problem on the specific configuration.
 
-4. Is the test failing on a Github Actions per-GHC build.
+4. Is the test failing on a GitHub Actions per-GHC build.
    In this case, if you click on "Branch", you can get access to
-   the precise binaries that were built by Github Actions that are being
+   the precise binaries that were built by GitHub Actions that are being
    tested.  If you have an Ubuntu system, you can download
    the binaries and run them directly.
 
@@ -176,7 +182,7 @@ Other Conventions
 * Our GHC support window is five years for the Cabal library and three
   years for cabal-install: that is, the Cabal library must be
   buildable out-of-the-box with the dependencies that shipped with GHC
-  for at least five years.  The Travis CI checks this, so most
+  for at least five years.  GitHub Actions checks this, so most
   developers submit a PR to see if their code works on all these
   versions of GHC.  `cabal-install` must also be buildable on all
   supported GHCs, although it does not have to be buildable
@@ -218,7 +224,7 @@ GitHub Ticket Conventions
 
 Each major `Cabal`/`cabal-install` release (e.g. 3.4, 3.6, etc.) has a
 corresponding GitHub Project and milestone. A ticket is included in a release's
-project if the release managers are tenatively planning on including a fix for
+project if the release managers are tentatively planning on including a fix for
 the ticket in the release, i.e. if they are actively seeking someone to work on
 the ticket.
 
@@ -247,6 +253,11 @@ If your pull request consists of several commits, consider using `squash+merge
 me` instead of `merge me`: the Mergify bot will squash all the commits into one
 and concatenate the commit messages of the commits before merging.
 
+There is also a `merge+no rebase` label. Use this very sparingly, as not rebasing
+severely complicates Git history. It is intended for special circumstances, as when
+the PR branch cannot or should not be modified. If you have any questions about it,
+please ask us.
+
 Changelog
 ---------