_find_changes.yaml

# Copyright 2025 Google LLC
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
#     https://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.

# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
# Explanation for why file changes are tested using this workflow.
#
# GitHub Actions workflows path filters (i.e., adding "paths:" keywords to
# event triggers) would be the natural way to trigger workflows only when
# relevant files are changed in a PR – except that the way GitHub branch
# protection rules work is: "If a workflow is skipped due to path filtering
# [...] the checks associated with that workflow will remain in a Pending
# state. A PR that requires those checks to be successful will be blocked from
# merging." This makes path filters unusable with merge queues. So, we forgo the
# use of path filters and instead check file changes using our own workflow.
# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

# The tilde is only to make our reusable workflows be listed last in the UI.
name: '~ Find changed files'
run-name: Determine which files have been changed

on:
  workflow_call:
    # N.B.: GitHub Actions workflow_call output values are ALWAYS strings, even
    # for (what you think are) Booleans. Consequently, calling workflows have to
    # test values using, e.g., ${{foo = 'false'}}, and not ${{foo}} or similar.
    outputs:
      code:
        description: 'True if any potential code file was changed'
        value: ${{jobs.test.outputs.nondoc-file-changes == 'true'}}
      python:
        description: 'True if any Python file was changed'
        value: ${{jobs.test.outputs.python-changes == 'true'}}

permissions: read-all

jobs:
  test:
    name: Inspect changes
    runs-on: ubuntu-24.04
    timeout-minutes: 5
    outputs:
      nondoc-file-changes: ${{steps.nondoc-files.outputs.matched}}
      python-changes: ${{steps.python-files.outputs.matched}}
    steps:
      - name: Check out a copy of the git repository
        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4

      - name: Test whether the changes involved one or more non-doc files
        uses: tomi/paths-filter-action@32c62f5ca100c1110406e3477d5b3ecef4666fec # v3.0.2
        id: nondoc-files
        with:
          base: ${{github.ref_name}}
          # Note: when editing the patterns below, always make sure to negate
          # the condition (i.e., use a leading '!'). See the next comment.
          filters: |
            matched:
              - '!.github/ISSUE_TEMPLATE/**'
              - '!.github/dependabot.yaml'
              - '!.github/problem-matchers/**'
              - '!CITATION.cff'
              - '!docs/**'
              - '!**/*.md'
              - '!**/*.png'
          # The default paths-filter-action behavior is "match at least one"
          # pattern. We change the behavior to be "match every" pattern.
          # Combined with negating every pattern above, it means the final output
          # will be non-empty only if there is at least one file that is NOT a
          # documentation file, or in other words, is a potential code file.
          predicate-quantifier: 'every'

      - name: Test whether Python files are among the changed files
        uses: tomi/paths-filter-action@32c62f5ca100c1110406e3477d5b3ecef4666fec # v3.0.2
        id: python-files
        with:
          base: ${{github.ref_name}}
          filters: |
            matched:
              - '**/*.py'

      - name: Summary of test results
        run: |
          set -x
          echo steps.nondoc-files.outputs.matched = │${{steps.nondoc-files.outputs.matched}}│
          echo steps.python-files.outputs.matched = │${{steps.python-files.outputs.matched}}│