Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Finish improvements to the CI configuration for documentation changes #9460

Merged
merged 6 commits into from
Nov 21, 2023
Merged
Show file tree
Hide file tree
Changes from 4 commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
39 changes: 39 additions & 0 deletions .github/workflows/bootstrap.skip.yml
Original file line number Diff line number Diff line change
@@ -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
28 changes: 28 additions & 0 deletions .github/workflows/bootstrap.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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
12 changes: 9 additions & 3 deletions .github/workflows/validate.skip.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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.
#
Expand All @@ -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
Expand Down
10 changes: 8 additions & 2 deletions .github/workflows/validate.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
6 changes: 6 additions & 0 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -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,
Expand Down
Loading