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.

Sign up for GitHub

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

Convert doc.yml workflow to be reusable #103914

Merged
merged 2 commits into from
May 28, 2023
Merged

Convert doc.yml workflow to be reusable #103914

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
ba7a9f9
🎨🧪 Convert `doc.yml` workflow to be reusable
webknjaz Apr 26, 2023
63e7b6b
Replace emojis in workflow and job names with text
webknjaz May 2, 2023
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
25 changes: 24 additions & 1 deletion .github/workflows/build.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -28,7 +28,7 @@ permissions:
contents: read

concurrency:
group: ${{ github.workflow }}-${{ github.head_ref || github.run_id }}
group: ${{ github.workflow }}-${{ github.head_ref || github.run_id }}-reusable
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This collides with the “parent” workflow if it's exactly the same, which is why it was required to introduce some difference.

cancel-in-progress: true

jobs:
Expand All @@ -37,6 +37,7 @@ jobs:
runs-on: ubuntu-latest
timeout-minutes: 10
outputs:
run-docs: ${{ steps.docs-changes.outputs.run-docs || false }}
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The part after || is only used as a fallback when the first part of the expression is empty (like when that step didn't even get executed).

run_tests: ${{ steps.check.outputs.run_tests }}
run_hypothesis: ${{ steps.check.outputs.run_hypothesis }}
config_hash: ${{ steps.config_hash.outputs.hash }}
Expand Down Expand Up @@ -79,6 +80,28 @@ jobs:
id: config_hash
run: |
echo "hash=${{ hashFiles('configure', 'configure.ac', '.github/workflows/build.yml') }}" >> $GITHUB_OUTPUT
- name: Get a list of the changed documentation-related files
if: github.event_name == 'pull_request'
id: changed-docs-files
uses: Ana06/[email protected]
with:
filter: |
Doc/**
Misc/**
.github/workflows/reusable-docs.yml
Comment on lines +88 to +91
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This reimplements what was implemented through paths:.

- name: Check for docs changes
if: >-
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If this step is skipped, the job output above will fall back to false.

github.event_name == 'pull_request'
&& steps.changed-docs-files.outputs.added_modified_renamed != ''
id: docs-changes
run: |
echo "run-docs=true" >> "${GITHUB_OUTPUT}"

check-docs:
name: Docs
needs: check_source
if: fromJSON(needs.check_source.outputs.run-docs)
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The job above sets either true or false as strings, parsing that as JSON allows not having equality checks.

uses: ./.github/workflows/reusable-docs.yml

check_generated_files:
name: 'Check if generated files are up to date'
Expand Down
25 changes: 1 addition & 24 deletions .github/workflows/doc.yml → .github/workflows/reusable-docs.yml
View file
Open in desktop
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I made the workflow file name prefixed with reusable- to start a convention that would help distinguish standalone workflows from the “inclusion snippets”.

Original file line number Diff line number Diff line change
@@ -1,31 +1,8 @@
name: Docs

on:
workflow_call:
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This bit is what allows to “include” this workflow into another.

workflow_dispatch:
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I kept this to make it possible to still trigger just this workflow separately, via a manual request.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@hugovk this is the only bit I wasn't sure about — is it useful to keep this trigger at all. If not, deleting it could improve maintainability..

#push:
# branches:
# - 'main'
# - '3.12'
# - '3.11'
# - '3.10'
# - '3.9'
# - '3.8'
# - '3.7'
# paths:
# - 'Doc/**'
pull_request:
branches:
- 'main'
- '3.12'
- '3.11'
- '3.10'
- '3.9'
- '3.8'
- '3.7'
paths:
- 'Doc/**'
- 'Misc/**'
- '.github/workflows/doc.yml'

permissions:
contents: read
Expand Down