build_workflow.yml

name: CI/CD Build Workflow

on:
  push:
    # When a branch is pushed to GitHub, run this workflow.
    # This will show up as the checks to pass on a pull request.
    branches: [main]

  pull_request:
    # When a pull request is merged, run this workflow.
    branches: [main]

  workflow_dispatch:

# These are the 4 jobs that show up under "All checks have passed" on GitHub.
jobs:
  # This job determines which jobs to skip.
  # It outputs a boolean value of whether to skip a job or not.
  # It uses a third party checker for duplicate actions.
  check-jobs-to-skip:
    runs-on: ubuntu-latest
    outputs:
      should_skip: ${{ steps.skip_check.outputs.should_skip }}
    steps:
      - id: skip_check
        uses: fkirc/skip-duplicate-actions@master
        with:
          cancel_others: false
          paths_ignore: '["**/README.md", "**/docs/**"]'

  pre-commit-hooks:
    needs: check-jobs-to-skip
    if: ${{ needs.check-jobs-to-skip.outputs.should_skip != 'true' }}
    runs-on: ubuntu-latest
    timeout-minutes: 5
    steps:
      - name: Checkout Code Repository
        uses: actions/checkout@v3

      - name: Set up Python 3.14
        uses: actions/setup-python@v4
        with:
          python-version: 3.14

      # Run all pre-commit hooks on all the files.
      # Getting only staged files can be tricky in case a new PR is opened
      # since the action is run on a branch in detached head state.
      # This is the equivalent of running "pre-commit run --all-files" locally.
      # If you commit with the `--no-verify` flag, this check may fail.
      - name: Install and Run Pre-commit
        uses: pre-commit/action@v3.0.1

  build:
    needs: check-jobs-to-skip
    if: ${{ needs.check-jobs-to-skip.outputs.should_skip != 'true' }}
    runs-on: ubuntu-latest
    strategy:
      matrix:
        python-version: ["3.11", "3.12", "3.13", "3.14"]
    defaults:
      run:
        shell: bash -l {0}
    steps:
      - uses: actions/checkout@v3

      - name: Cache Conda
        uses: actions/cache@v3
        env:
          CACHE_NUMBER: 1 # Increment this to invalidate cache
        with:
          path: ~/conda_pkgs_dir
          key: ${{ runner.os }}-conda-${{ env.CACHE_NUMBER }}-${{
            hashFiles('conda/dev.yml') }}-python${{ matrix.python-version }}

      - name: Build Conda Environment
        uses: conda-incubator/setup-miniconda@v3
        with:
          activate-environment: zppy_dev
          miniforge-variant: Miniforge3
          miniforge-version: latest
          environment-file: conda/dev.yml
          channel-priority: flexible # Changed from strict to flexible
          auto-update-conda: true
          python-version: ${{ matrix.python-version }}
          channels: conda-forge
          use-only-tar-bz2: true

      - name: Verify Environment and Fix Dependencies
        run: |
          conda info
          conda list
          # Ensure we have the right Python version
          python --version
          # Fix pip issues for Python 3.12+
          if [[ "${{ matrix.python-version }}" == "3.12" ]] || [[ "${{ matrix.python-version }}" == "3.13" ]] || [[ "${{ matrix.python-version }}" == "3.14" ]]; then
            python -m ensurepip --upgrade || true
            python -m pip install --upgrade --force-reinstall pip setuptools wheel
          fi

      - if: ${{ needs.check-jobs-to-skip.outputs.should_skip != 'true' }}
        name: Show Conda Environment Info
        run: |
          conda config --set anaconda_upload no
          conda info
          conda list

      - name: Install `zppy` Package
        run: python -m pip install .

      # Does not run the integration tests, which require server access
      - name: Run Unit Tests
        run: |
          pytest tests/test_*.py

  # If the branch updates documentation, then the docs will need to be updated.
  publish-docs:
    if: ${{ github.event_name == 'push' }}
    runs-on: ubuntu-latest
    defaults:
      run:
        shell: bash -l {0}
    timeout-minutes: 10 # Increased timeout for docs
    steps:
      - uses: actions/checkout@v2
        with:
          persist-credentials: false
          fetch-depth: 0

      - name: Cache Conda
        uses: actions/cache@v3
        env:
          CACHE_NUMBER: 1 # Match the build job cache number
        with:
          path: ~/conda_pkgs_dir
          key: ${{ runner.os }}-conda-${{ env.CACHE_NUMBER }}-${{
            hashFiles('conda/dev.yml') }}-docs

      - name: Build Conda Environment
        uses: conda-incubator/setup-miniconda@v3
        with:
          activate-environment: zppy_dev
          miniforge-variant: Miniforge3
          miniforge-version: latest
          environment-file: conda/dev.yml
          channel-priority: flexible # Changed from strict to flexible
          auto-update-conda: true
          python-version: "3.14" # Use stable Python version for docs

      - if: ${{ needs.check-jobs-to-skip.outputs.should_skip != 'true' }}
        name: Show Conda Environment Info
        run: |
          conda config --set anaconda_upload no
          conda info
          conda list

      - name: Install `zppy` Package
        run: pip install .

      # sphinx-multiversion allows for version docs.
      - name: Build Sphinx Docs
        run: |
          cd docs
          sphinx-multiversion source _build/html

      - name: Copy Docs and Commit
        run: |
          # gh-pages branch must already exist
          git clone https://github.com/E3SM-Project/zppy.git --branch gh-pages --single-branch gh-pages

          # Only replace main docs with latest changes. Docs for tags should be untouched.
          cd gh-pages
          rm -r _build/html/main
          cp -r ../docs/_build/html/main _build/html/main
          git config --local user.email "41898282+github-actions[bot]@users.noreply.github.com"
          git config --local user.name "github-actions[bot]"

          # The below command will fail if no changes were present, so we ignore it
          git add .
          git commit -m "Update documentation" -a || true

      - name: Push Changes
        uses: ad-m/github-push-action@master
        with:
          branch: gh-pages
          directory: gh-pages
          github_token: ${{ secrets.GITHUB_TOKEN }}
          force: true