From 60aa93de2ad27e8afefce5cf1ffe6016b66cd9c1 Mon Sep 17 00:00:00 2001 From: David Binder Date: Sun, 19 Nov 2023 00:13:44 +0100 Subject: [PATCH 1/5] Add bootstrap postjob to CI config Add a new job to the bootstrap.yml GitHub action config. This job succeeds if, and only if, all the other bootstrap jobs succeed. --- .github/workflows/bootstrap.yml | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) diff --git a/.github/workflows/bootstrap.yml b/.github/workflows/bootstrap.yml index c1734736e4c..79bee406243 100644 --- a/.github/workflows/bootstrap.yml +++ b/.github/workflows/bootstrap.yml @@ -66,3 +66,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 From bec128456d4b5637582839e159c3fd9b6ae0417b Mon Sep 17 00:00:00 2001 From: David Binder Date: Sun, 19 Nov 2023 00:20:59 +0100 Subject: [PATCH 2/5] Do not run bootstrap CI jobs for documentation changes The approach was already introduced in #9355 for the validate jobs. This commit introduces the same change also for the bootstrap jobs. --- .github/workflows/bootstrap.skip.yml | 33 ++++++++++++++++++++++++++++ .github/workflows/bootstrap.yml | 2 ++ 2 files changed, 35 insertions(+) create mode 100644 .github/workflows/bootstrap.skip.yml diff --git a/.github/workflows/bootstrap.skip.yml b/.github/workflows/bootstrap.skip.yml new file mode 100644 index 00000000000..d1b1444620c --- /dev/null +++ b/.github/workflows/bootstrap.skip.yml @@ -0,0 +1,33 @@ +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/**' + branches: + - master + pull_request: + paths: 'doc/**' + release: + types: + - created + +jobs: + bootstrap-post-job: + if: always() + name: Bootstrap post job + runs-on: ubuntu-latest + steps: + - run: exit 0 diff --git a/.github/workflows/bootstrap.yml b/.github/workflows/bootstrap.yml index 79bee406243..6e647ecd7b4 100644 --- a/.github/workflows/bootstrap.yml +++ b/.github/workflows/bootstrap.yml @@ -7,9 +7,11 @@ concurrency: on: push: + paths-ignore: 'doc/**' branches: - master pull_request: + paths-ignore: 'doc/**' release: types: - created From bd21dc930b4015442d8305aec8477637c90040ef Mon Sep 17 00:00:00 2001 From: David Binder Date: Sun, 19 Nov 2023 00:30:02 +0100 Subject: [PATCH 3/5] Also ignore CONTRIBUTING.md and README.md in CI We do not run the entire CI suite for documentation changes. Previously, only changes which were restricted to the 'docs/' subdirectory were considered to be documentation changes. With this commit we also recognize changes to README.md and CONTRIBUTING.md as documentation changes. --- .github/workflows/bootstrap.skip.yml | 12 +++++++++--- .github/workflows/bootstrap.yml | 13 +++++++++++-- .github/workflows/validate.skip.yml | 12 +++++++++--- .github/workflows/validate.yml | 10 ++++++++-- 4 files changed, 37 insertions(+), 10 deletions(-) diff --git a/.github/workflows/bootstrap.skip.yml b/.github/workflows/bootstrap.skip.yml index d1b1444620c..d0c259724df 100644 --- a/.github/workflows/bootstrap.skip.yml +++ b/.github/workflows/bootstrap.skip.yml @@ -5,7 +5,7 @@ name: Bootstrap Skip # 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 +# "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. # @@ -15,11 +15,17 @@ name: Bootstrap Skip # finish successfully. on: push: - paths: 'doc/**' + paths: + - 'doc/**' + - 'README.md' + - 'CONTRIBUTING.md' branches: - master pull_request: - paths: 'doc/**' + paths: + - 'doc/**' + - 'README.md' + - 'CONTRIBUTING.md' release: types: - created diff --git a/.github/workflows/bootstrap.yml b/.github/workflows/bootstrap.yml index 6e647ecd7b4..5e266e97889 100644 --- a/.github/workflows/bootstrap.yml +++ b/.github/workflows/bootstrap.yml @@ -5,13 +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/**' + paths-ignore: + - 'doc/**' + - 'README.md' + - 'CONTRIBUTING.md' branches: - master pull_request: - paths-ignore: 'doc/**' + paths-ignore: + - 'doc/**' + - 'README.md' + - 'CONTRIBUTING.md' release: types: - created diff --git a/.github/workflows/validate.skip.yml b/.github/workflows/validate.skip.yml index b67d41dd2c4..9c0dc5f2f0f 100644 --- a/.github/workflows/validate.skip.yml +++ b/.github/workflows/validate.skip.yml @@ -5,7 +5,7 @@ name: Validate Skip # 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 +# "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. # @@ -15,11 +15,17 @@ name: Validate Skip # finish successfully. on: push: - paths: 'doc/**' + paths: + - 'doc/**' + - 'README.md' + - 'CONTRIBUTING.md' branches: - master pull_request: - paths: 'doc/**' + paths: + - 'doc/**' + - 'README.md' + - 'CONTRIBUTING.md' release: types: - created diff --git a/.github/workflows/validate.yml b/.github/workflows/validate.yml index aa6d01a128d..eac90f9bc1c 100644 --- a/.github/workflows/validate.yml +++ b/.github/workflows/validate.yml @@ -16,11 +16,17 @@ concurrency: # "validate.skip.yml" for a description of the problem and the solution provided in that file. on: push: - paths-ignore: 'doc/**' + paths-ignore: + - 'doc/**' + - 'README.md' + - 'CONTRIBUTING.md' branches: - master pull_request: - paths-ignore: 'doc/**' + paths-ignore: + - 'doc/**' + - 'README.md' + - 'CONTRIBUTING.md' release: types: - created From 866fa07b7531d507e0d9176dafda79f3b47dea5e Mon Sep 17 00:00:00 2001 From: David Binder Date: Sun, 19 Nov 2023 00:37:14 +0100 Subject: [PATCH 4/5] Document improved CI for documentation in CONTRIBUTING.md The CONTRIBUTING.md file now mentions that documentation changes do not waste expensive CI resources. --- CONTRIBUTING.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index c8149330eb5..cf3357a71d4 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -51,6 +51,12 @@ Some tips for using GitHub Actions effectively: sure everything is OK; otherwise, try to run relevant tests locally first. +* 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, From 36a32f499fb61bbb6448fd9e828c4f73736cb3fb Mon Sep 17 00:00:00 2001 From: David Binder Date: Sun, 19 Nov 2023 18:38:31 +0100 Subject: [PATCH 5/5] Recognize all README.md in subdirs as documentation Expensive CI jobs should not run on changes which affect only README.md files. --- .github/workflows/bootstrap.skip.yml | 4 ++-- .github/workflows/bootstrap.yml | 4 ++-- .github/workflows/validate.skip.yml | 4 ++-- .github/workflows/validate.yml | 4 ++-- 4 files changed, 8 insertions(+), 8 deletions(-) diff --git a/.github/workflows/bootstrap.skip.yml b/.github/workflows/bootstrap.skip.yml index d0c259724df..4a92ddaa0c6 100644 --- a/.github/workflows/bootstrap.skip.yml +++ b/.github/workflows/bootstrap.skip.yml @@ -17,14 +17,14 @@ on: push: paths: - 'doc/**' - - 'README.md' + - '**/README.md' - 'CONTRIBUTING.md' branches: - master pull_request: paths: - 'doc/**' - - 'README.md' + - '**/README.md' - 'CONTRIBUTING.md' release: types: diff --git a/.github/workflows/bootstrap.yml b/.github/workflows/bootstrap.yml index 5e266e97889..03dafc3f59d 100644 --- a/.github/workflows/bootstrap.yml +++ b/.github/workflows/bootstrap.yml @@ -12,14 +12,14 @@ on: push: paths-ignore: - 'doc/**' - - 'README.md' + - '**/README.md' - 'CONTRIBUTING.md' branches: - master pull_request: paths-ignore: - 'doc/**' - - 'README.md' + - '**/README.md' - 'CONTRIBUTING.md' release: types: diff --git a/.github/workflows/validate.skip.yml b/.github/workflows/validate.skip.yml index 9c0dc5f2f0f..e5cd47e284a 100644 --- a/.github/workflows/validate.skip.yml +++ b/.github/workflows/validate.skip.yml @@ -17,14 +17,14 @@ on: push: paths: - 'doc/**' - - 'README.md' + - '**/README.md' - 'CONTRIBUTING.md' branches: - master pull_request: paths: - 'doc/**' - - 'README.md' + - '**/README.md' - 'CONTRIBUTING.md' release: types: diff --git a/.github/workflows/validate.yml b/.github/workflows/validate.yml index eac90f9bc1c..78652b10af7 100644 --- a/.github/workflows/validate.yml +++ b/.github/workflows/validate.yml @@ -18,14 +18,14 @@ on: push: paths-ignore: - 'doc/**' - - 'README.md' + - '**/README.md' - 'CONTRIBUTING.md' branches: - master pull_request: paths-ignore: - 'doc/**' - - 'README.md' + - '**/README.md' - 'CONTRIBUTING.md' release: types: