Merge remote-tracking branch 'upstream/master' into parse-cabal-proje…

…ct-parsec

.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!*)
 
 ---
 
@@ -20,4 +19,5 @@ Bonus points for added automated tests!
 Include the following checklist in your PR:
 
 * [ ] Patches conform to the [coding conventions](https://github.com/haskell/cabal/blob/master/CONTRIBUTING.md#other-conventions).
+* [ ] Is this a PR that fixes CI? If so, it will need to be backported to older cabal release branches (ask maintainers for directions).
 

.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
@@ -19,13 +30,19 @@ jobs:
     strategy:
       matrix:
         os: [ubuntu-latest]
-        ghc: ["8.10.7", "9.0.2", "9.2.7", "9.4.4"]
+        ghc: ["8.10.7", "9.0.2", "9.2.8", "9.4.8", "9.6.4", "9.8.1"]
         include:
           - os: macos-latest
-            ghc: "9.2.7"
+            ghc: "9.2.8"
     name: Bootstrap ${{ matrix.os }} ghc-${{ matrix.ghc }}
     runs-on: ${{ matrix.os }}
     steps:
+      - name: Work around XDG directories existence (haskell-actions/setup#62)
+        if: ${{ runner.os == 'macOS' }}
+        run: |
+          rm -rf ~/.config/cabal
+          rm -rf ~/.cache/cabal
+
       - uses: actions/cache@v3
         name: Cache the downloads
         id: bootstrap-cache
@@ -66,3 +83,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/changelogs.yml

@@ -48,12 +48,14 @@ jobs:
           ghcup set ghc recommended
       - name: Update Hackage index
         run: cabal v2-update
-      # Cannot install it from tarball due to
+      # Cannot install it directly from remote tarball due to
       # https://github.com/haskell/cabal/issues/7360
-      - uses: actions/checkout@v4
-        with:
-          repository: "fgaz/changelog-d"
-          path: "changelog-d"
+      - name: Fetch changelog-d
+        run: |
+          changelog_d_latest="$(curl https://codeberg.org/api/v1/repos/fgaz/changelog-d/branches/master | jq -r .commit.id)"
+          echo "Using changelog-d revision $changelog_d_latest"
+          curl "https://codeberg.org/fgaz/changelog-d/archive/$changelog_d_latest.tar.gz" -o changelog-d.tar.gz
+          tar -xf changelog-d.tar.gz
       - name: Install changelog-d
         run: |
           pushd changelog-d

.github/workflows/format.yml

@@ -10,7 +10,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
     - uses: actions/checkout@v4
-    - uses: haskell-actions/run-fourmolu@v9
+    - uses: haskell-actions/run-fourmolu@v10
       with:
         version: "0.12.0.0"
         pattern: |

.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/quick-jobs.yml

@@ -18,77 +18,125 @@ jobs:
   meta:
     name: Meta checks
     runs-on: ubuntu-latest
+    env:
+      cabal_build: >-
+        cabal build --builddir=dist-newstyle-meta --project-file=cabal.project.meta
+        gen-cabal-macros
+        gen-paths-module
+        gen-spdx
+        gen-spdx-exc
     # This job is not run in a container, any recent GHC should be fine
     steps:
-      - name: Set PATH
-        # https://docs.github.com/en/free-pro-team@latest/actions/reference/workflow-commands-for-github-actions#adding-a-system-path
+      # SKIP installation of ghc and cabal and use the preinstalled versions.
+      # - name: ghcup
+      #   run: |
+      #     ghcup --version
+      #     ghcup config set cache true
+      #     ghcup install ghc recommended
+      #     ghcup set ghc recommended
+      - name: Haskell versions
         run: |
-          echo "$HOME/.cabal/bin" >> $GITHUB_PATH
-      - uses: actions/cache@v3
-        with:
-          path: ~/.cabal/store
-          key: linux-store-meta
-      # See https://github.com/haskell/cabal/pull/8739
-      - name: Sudo chmod to permit ghcup to update its cache
-        run: |
-          if [[ "${{ runner.os }}" == "Linux" ]]; then
-            sudo ls -lah /usr/local/.ghcup/cache
-            sudo mkdir -p /usr/local/.ghcup/cache
-            sudo ls -lah /usr/local/.ghcup/cache
-            sudo chown -R $USER /usr/local/.ghcup
-            sudo chmod -R 777 /usr/local/.ghcup
-          fi
-      - name: ghcup
-        run: |
-          ghcup --version
-          ghcup config set cache true
-          ghcup install ghc recommended
-          ghcup set ghc recommended
+          ghc --version
+          cabal --version
       - name: Update Hackage index
         run: cabal v2-update
-      - name: Install alex
-        run: cabal v2-install alex --constraint='alex ==3.2.7.3'
       - uses: actions/checkout@v4
+      - name: Generate build plan for correct cache key
+        run: ${{ env.cabal_build }} --dry-run
+      - name: Restore cached dependencies
+        uses: actions/cache/restore@v4
+        id: cache
+        with:
+          path: ~/.local/state/cabal
+          key: linux-store-meta-${{ hashfiles('dist-newstyle-meta/cache/plan.json') }}
+          restore-keys: linux-store-meta-
+      - name: Build tools
+        run: ${{ env.cabal_build }}
       - name: Regenerate files
         run: |
-          make -B lexer
           make -B spdx
           make -B templates
       - name: Check that diff is clean
         run: |
           git status > /dev/null
           git diff-files -p --exit-code
+      - name: Cache dependencies
+        uses: actions/cache/save@v4
+        if: always() && steps.cache.outputs.cache-hit != 'true'
+        with:
+          path: ~/.local/state/cabal
+          key: ${{ steps.cache.outputs.cache-primary-key }}
+
   doctest:
     name: Doctest Cabal
     runs-on: ubuntu-latest
     steps:
-      - name: Set PATH
+      # It is complicated to get a proper cache key for the dependencies of a package
+      # (here: doctest) that we just `cabal install`.
+      # So, as a heuristics we update the cache once per day.
+      # Updating it with each run would be an alternative, but we a short of cache space,
+      # and this would generate too many new caches.
+      - name: Use date as cache key
         run: |
-          echo "$HOME/.cabal/bin" >> $GITHUB_PATH
-      - uses: actions/cache@v3
+          echo "DATE=$(date +'%Y-%m-%d')" >> "${GITHUB_ENV}"
+      - name: Restore cached dependencies
+        uses: actions/cache/restore@v4
+        id: cache
         with:
-          path: ~/.cabal/store
-          key: linux-store-doctest
-      # See https://github.com/haskell/cabal/pull/8739
-      - name: Sudo chmod to permit ghcup to update its cache
-        run: |
-          if [[ "${{ runner.os }}" == "Linux" ]]; then
-            sudo ls -lah /usr/local/.ghcup/cache
-            sudo mkdir -p /usr/local/.ghcup/cache
-            sudo ls -lah /usr/local/.ghcup/cache
-            sudo chown -R $USER /usr/local/.ghcup
-            sudo chmod -R 777 /usr/local/.ghcup
-          fi
-      - name: ghcup
-        run: |
-          ghcup --version
-          ghcup config set cache true
-          ghcup install ghc --set recommended
-          ghcup install cabal --set latest
+          path: ~/.local/state/cabal
+          key: linux-store-doctest-${{ env.DATE }}
+          restore-keys: linux-store-doctest
       - name: Update Hackage index
         run: cabal v2-update
       - uses: actions/checkout@v4
       - name: Install doctest
         run: make doctest-install
       - name: Doctest
         run: make doctest
+      - name: Cache dependencies
+        if: always() && steps.cache.outputs.cache-hit != 'true'
+        uses: actions/cache/save@v4
+        with:
+          path: ~/.local/state/cabal
+          key: ${{ steps.cache.outputs.cache-primary-key }}
+
+  buildinfo:
+    name: Check Field Syntax Reference
+    runs-on: ubuntu-latest
+    env:
+      cabal_build: cabal build buildinfo-reference-generator
+    steps:
+      - name: Update Hackage index
+        run: cabal v2-update
+      - uses: actions/checkout@v4
+      - name: Generate build plan for correct cache key
+        run: ${{ env.cabal_build }} --dry-run
+      - name: Restore cached dependencies
+        uses: actions/cache/restore@v4
+        id: cache
+        with:
+          path: ~/.local/state/cabal
+          key: linux-store-buildinfo-doc-diff-${{ hashfiles('dist-newstyle/cache/plan.json') }}
+          restore-keys: linux-store-buildinfo-doc-diff
+      - name: Build buildinfo-reference-generator
+        run: ${{ env.cabal_build }}
+      - name: Are buildinfo docs up to date?
+        run: make doc/buildinfo-fields-reference.rst
+      - name: Cache dependencies
+        uses: actions/cache/save@v4
+        if: always() && steps.cache.outputs.cache-hit != 'true'
+        with:
+          path: ~/.local/state/cabal
+          key: ${{ steps.cache.outputs.cache-primary-key }}
+
+  release-project:
+    name: Check Release Project
+    runs-on: ubuntu-latest
+    steps:
+      - name: Update Hackage Index
+        run: cabal v2-update
+      - uses: actions/checkout@v4
+      - name: Check Release with Pinned Hackage
+        run: cabal build all --dry-run --project-file=cabal.project.release
+      - name: Check Release with Latest Hackage
+        run: cabal build all --dry-run --project-file=cabal.project.release --index-state="hackage.haskell.org HEAD"

.github/workflows/users-guide.yml

@@ -54,7 +54,7 @@ jobs:
         submodules: recursive
 
     - name: Set up Python ${{ matrix.python-version }}
-      uses: actions/setup-python@v4
+      uses: actions/setup-python@v5
       with:
         python-version: ${{ matrix.python-version }}
 

.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