release_dispatch.yml

name: MODFLOW 6 release dispatch
on:
  push:
    branches:
      # initial phase of the release procedure is triggered by pushing a release branch for
      # a patch release (patch version 1-9, then anything). A new minor release, vX.Y.0,
      # needs its DOI as input so is started via dispatch.
      - v[0-9]+.[0-9]+.[1-9]*
      # intermediate phase is triggered by merging the release branch to master
      - master
  # final phase is triggered by promoting/publishing a GitHub release draft to a full release
  release:
    types:
      - published
  # workflow_dispatch trigger to start release via GitHub UI or CLI,
  # as an alternative to triggering when a release branch is pushed.
  # see https://docs.github.com/en/actions/managing-workflow-runs/manually-running-a-workflow
  workflow_dispatch:
    inputs:
      branch:
        description: 'Branch to release from.'
        required: true
        type: string
      compiler_toolchain:
        description: 'Compiler toolchain to use. For supported options see https://github.com/MODFLOW-ORG/modflow6/blob/develop/DEVELOPER.md#compiler-compatibility.'
        required: false
        type: string
        default: 'intel-classic'
      compiler_version:
        description: 'Compiler version to use. For supported options see https://github.com/MODFLOW-ORG/modflow6/blob/develop/DEVELOPER.md#compiler-compatibility.'
        required: false
        type: string
        default: '2021.6'
      run_tests:
        description: 'Run tests after building binaries.'
        required: false
        type: boolean
        default: true
      version:
        description: 'Version number to use for release.'
        required: true
        type: string
      patch:
        description: 'Create a patch release. If true, only bug fixes and new examples will be included in generated documentation.'
        required: false
        type: boolean
        default: false
      doi:
        description: 'DOI link of the release, e.g. https://doi.org/10.5066/P1PGE9XW, for the release history in the release notes. Required for a new minor release unless its release history row was already added to the release branch. Patch releases reuse the DOI of the minor release they patch.'
        required: false
        type: string
jobs:
  set_options:
    name: Set release options
    if: github.event_name != 'release' && github.ref_name != 'master'
    runs-on: ubuntu-22.04
    defaults:
      run:
        shell: bash -l {0}
    outputs:
      branch: ${{ steps.set_branch.outputs.branch }}
      compiler_toolchain: ${{ steps.set_compiler.outputs.compiler_toolchain }}
      compiler_version: ${{ steps.set_compiler.outputs.compiler_version }}
      version: ${{ steps.set_version.outputs.version }}
      patch: ${{ steps.set_patch.outputs.patch }}
    steps:
      - name: Checkout modflow6
        uses: actions/checkout@v7
        with:
          repository: ${{ github.repository_owner }}/modflow6
          ref: ${{ github.ref }}
      - name: Set branch
        id: set_branch
        run: |
          # if branch was provided explicitly via workflow_dispatch, use it
          if [[ ("${{ github.event_name }}" == "workflow_dispatch") && (-n "${{ inputs.branch }}") ]]; then
            branch="${{ inputs.branch }}"
            # prevent releases from master
            if [[ "$branch" == "master" ]]; then
              echo "error: releases may not be triggered from branch $branch"
              exit 1
            fi
            echo "using branch $branch from workflow_dispatch"
          elif [[ ("${{ github.event_name }}" == "push") && ("${{ github.ref_name }}" != "master") ]]; then
            # if release was triggered by pushing a release branch, use that branch
            branch="${{ github.ref_name }}"
            echo "using branch $branch from ref ${{ github.ref }}"
          else
            # otherwise exit with an error
            echo "error: this workflow should not have triggered for event ${{ github.event_name }} on branch ${{ github.ref_name }}"
            exit 1
          fi
          echo "branch=$branch" >> $GITHUB_OUTPUT
      - name: Set compiler
        id: set_compiler
        run: |
          # if compiler toolchain was provided explicitly via workflow_dispatch, use it
          if [[ ("${{ github.event_name }}" == "workflow_dispatch") && (-n "${{ inputs.compiler_toolchain }}") ]]; then
            compiler_toolchain="${{ inputs.compiler_toolchain }}"
            compiler_version="${{ inputs.compiler_version }}"
            echo "using compiler toolchain $compiler_toolchain version $compiler_version from workflow_dispatch"
          elif [[ ("${{ github.event_name }}" == "push") && ("${{ github.ref_name }}" != "master") ]]; then
            # if release was triggered by pushing a release branch, use the default toolchain and version
            compiler_toolchain="intel-classic"
            compiler_version="2021.6"
            echo "using default compiler toolchain $compiler_toolchain version $compiler_version"
          else
            # otherwise exit with an error
            echo "error: this workflow should not have triggered for event ${{ github.event_name }} on branch ${{ github.ref_name }}"
            exit 1
          fi
          echo "compiler_toolchain=$compiler_toolchain" >> $GITHUB_OUTPUT
          echo "compiler_version=$compiler_version" >> $GITHUB_OUTPUT
      - name: Set version
        id: set_version
        run: |
          # if version number was provided explicitly via workflow_dispatch, use it
          if [[ ("${{ github.event_name }}" == "workflow_dispatch") && (-n "${{ inputs.version }}") ]]; then
            ver="${{ inputs.version }}"
            echo "using version number $ver from workflow_dispatch"
          elif [[ ("${{ github.event_name }}" == "push") && ("${{ github.ref_name }}" != "master") ]]; then
            # if release was triggered by pushing a release branch, parse version number from branch name (sans leading 'v')
            ref="${{ github.ref_name }}"
            ver="${ref#"v"}"
            echo "parsed version number $ver from branch name $ref"
          else
            # otherwise exit with an error
            echo "error: version number not provided explicitly (via workflow_dispatch input) or implicitly (via branch name)"
            exit 1
          fi
          echo "version=$ver" >> $GITHUB_OUTPUT
      - name: Set patch
        id: set_patch
        run: |
          # if patch was provided explicitly via workflow_dispatch, use it
          if [[ ("${{ github.event_name }}" == "workflow_dispatch") && (-n "${{ inputs.patch }}") ]]; then
            patch="${{ inputs.patch }}"
            echo "using patch setting $patch from workflow_dispatch"
          elif [[ ("${{ github.event_name }}" == "push") && ("${{ github.ref_name }}" != "master") ]]; then
            # if release was triggered by pushing a release branch, check the version against the latest
            # tag on master to determine if this is a patch release
            latest_tag=$(git ls-remote --tags origin "6.*" | awk -F/ '{print $3}' | sort -V | tail -n1)
            echo "latest version on master is $latest_tag"
            IFS='.' read -r -a latest_parts <<< "$latest_tag"
            IFS='.' read -r -a new_parts <<< "${{ steps.set_version.outputs.version }}"
            if [[ ${#latest_parts[@]} -ne 3 || ${#new_parts[@]} -ne 3 ]]; then
              echo "error: version number is not in major.minor.patch format"
              exit 1
            fi
            if [[ ${latest_parts[0]} -ne ${new_parts[0]} || ${latest_parts[1]} -ne ${new_parts[1]} ]]; then
              patch="false"
              echo "major or minor version has changed, not a patch release"
            elif [[ ${latest_parts[2]} -lt ${new_parts[2]} ]]; then
              patch="true"
              echo "patch version has changed, this is a patch release"
            fi
          else
            # otherwise exit with an error
            echo "error: this workflow should not have triggered for event ${{ github.event_name }} on branch ${{ github.ref_name }}"
            exit 1
          fi
          echo "patch=$patch" >> $GITHUB_OUTPUT
      - name: Check release history
        env:
          BRANCH: ${{ steps.set_branch.outputs.branch }}
          VERSION: ${{ steps.set_version.outputs.version }}
          DOI: ${{ inputs.doi }}
        run: |
          # release.yml adds the release history row. Patch releases reuse the previous DOI,
          # but a new minor release needs one, from the doi input or a row already on the
          # branch. Fail now instead of in the build if there isn't one.
          git fetch --depth=1 origin "$BRANCH"
          git show FETCH_HEAD:doc/ReleaseNotes/ReleaseNotes.tex > "$RUNNER_TEMP/ReleaseNotes.tex"
          args=(-v "$VERSION" --check --notes "$RUNNER_TEMP/ReleaseNotes.tex")
          if [[ -n "$DOI" ]]; then
            args+=(--doi "$DOI")
          fi
          if ! python3 doc/ReleaseNotes/release_history.py "${args[@]}"; then
            echo "Start the release with workflow_dispatch and provide the doi input, or add a row"
            echo "for $VERSION to the release history in doc/ReleaseNotes/ReleaseNotes.tex on $BRANCH."
            exit 1
          fi
  make_dist:
    name: Make distribution
    uses: MODFLOW-ORG/modflow6/.github/workflows/release.yml@develop
    needs: set_options
    with:
      compiler_toolchain: ${{ needs.set_options.outputs.compiler_toolchain }}
      compiler_version: ${{ needs.set_options.outputs.compiler_version }}
      # release.yml commits the release metadata on top, which the pr job pushes
      ref: ${{ needs.set_options.outputs.branch }}
      releasemode: true
      # If the workflow is manually triggered, the maintainer must manually set run_tests to false, otherwise the default is true.
      # If triggered by pushing a release branch, tests are enabled.
      run_tests: ${{ (github.event_name == 'workflow_dispatch' && inputs.run_tests == true) || github.event_name != 'workflow_dispatch' }}
      version: ${{ needs.set_options.outputs.version }}
      patch: ${{ (github.event_name == 'workflow_dispatch' && inputs.patch == true) || (github.event_name != 'workflow_dispatch' && needs.set_options.outputs.patch == 'true') }}
      # empty if triggered by push (see Check release history)
      doi: ${{ inputs.doi }}
  pr:
    name: Draft release PR
    needs:
      - set_options
      - make_dist
    runs-on: ubuntu-22.04
    permissions:
      contents: write
      pull-requests: write
    steps:
      - name: Checkout modflow6
        uses: MODFLOW-ORG/modflow6/.github/actions/checkout-release@develop
        with:
          sha: ${{ needs.make_dist.outputs.sha }}

      # if release.yml made no release commit, this just checks the branch hasn't moved
      - name: Push release commit
        working-directory: modflow6
        env:
          BRANCH: ${{ needs.set_options.outputs.branch }}
          SHA: ${{ needs.make_dist.outputs.sha }}
        run: |
          # not forced, so a branch that moved during the build isn't overwritten
          if ! git push origin "$SHA:refs/heads/$BRANCH"; then
            echo "::error::Couldn't push to $BRANCH, which may have moved since the release started. Rerun the release."
            exit 1
          fi

      - name: Create pull request
        env:
          GITHUB_TOKEN: ${{ github.token }}
          BRANCH: ${{ needs.set_options.outputs.branch }}
        run: |
          ver="${{ needs.set_options.outputs.version }}"

          # a rerun after the release PR was opened (e.g. to rebuild after pushing a
          # fix to the release branch) updates that PR's branch, so don't open another
          existing=$(gh pr list -R "${{ github.repository }}" -B master -H "$BRANCH" --state open --json url --jq '.[0].url // empty')
          if [[ -n "$existing" ]]; then
            echo "release PR already exists for $BRANCH: $existing"
            exit 0
          fi

          body='
          # MODFLOW '$ver' release

          The release can be approved by merging this PR into `master`. Merging rather than squashing is necessary to preserve the commit history.

          When this PR is merged, a final job will be triggered to draft a tagged GitHub release, then upload assets (OS distributions and release notes).
          '
          gh pr create -B "master" -H "$BRANCH" -R "${{ github.repository }}" --title "Release $ver" --draft --body "$body"

  release:
    name: Draft release
    # runs only after release PR is merged to master
    if: github.event_name == 'push' && github.ref_name == 'master'
    runs-on: ubuntu-22.04
    defaults:
      run:
        shell: bash -l {0}
    steps:
      - name: Checkout modflow6
        uses: actions/checkout@v7
        with:
          repository: ${{ github.repository_owner }}/modflow6
          path: modflow6

      - name: Setup Micromamba
        uses: mamba-org/setup-micromamba@v3
        with:
          environment-file: modflow6/environment.yml
          cache-downloads: true
          cache-environment: true

      - name: Download artifacts
        uses: dawidd6/action-download-artifact@v27

      - name: Draft release
        working-directory: modflow6
        env:
          GITHUB_TOKEN: ${{ github.token }}
        run: |
          # create draft release
          version=$(python distribution/update_version.py -g)
          title="MODFLOW $version"
          citation=$(python distribution/update_version.py -c)
          notes='
          This is the approved USGS MODFLOW '$version' release.
      
          '$citation'
      
          Visit the USGS "MODFLOW and Related Programs" site for information on MODFLOW 6 and related software: https://doi.org/10.5066/F76Q1VQV
          '
          gh release create "$version" ../mf*/mf*.zip ../release_notes/release.pdf --target master --title "$title" --notes "$notes" --draft --latest

  reset:
    name: Reset develop
    # runs after a release is published. opens a PR to merge master back
    # into develop with the version string updated for the next cycle
    if: github.event_name == 'release'
    runs-on: ubuntu-22.04
    permissions:
      contents: write
      pull-requests: write
    defaults:
      run:
        shell: bash -l {0}
    steps:
      - name: Checkout modflow6
        uses: actions/checkout@v7
        with:
          repository: ${{ github.repository_owner }}/modflow6
          ref: master
          fetch-depth: 0

      - name: Setup Micromamba
        uses: mamba-org/setup-micromamba@v3
        with:
          environment-file: environment.yml
          cache-downloads: true
          cache-environment: true

      - name: Archive release notes
        working-directory: doc/ReleaseNotes
        run: |
          # the released version, since we branched from master (and this runs
          # before the version bump below)
          ver=$(cat ../../version.txt)

          # a non-zero patch number means a patch release: archive and clear
          # only the fix and example items, the rest carry to the next minor release
          patch=""
          [ "$(echo "$ver" | cut -d. -f3)" != "0" ] && patch="--patch"

          # archive this version's notes to previous/v$ver.tex, register them
          # in appendixA.tex, and delete the archived item files
          python reset_releasenotes.py $patch

      - name: Update version and open PR
        working-directory: distribution
        env:
          GITHUB_TOKEN: ${{ github.token }}
        run: |
          # the released version, since we branched from master
          ver=$(cat ../version.txt)
          branch="post-release-$ver-reset"

          # bump minor and add '.dev0' suffix
          next=$(python update_version.py --post-release)

          # lint the generated source
          fprettify -c ../.fprettify.yaml ../src/Utilities/version.f90

          # commit and push
          git config core.sharedRepository true
          git config user.name "github-actions[bot]"
          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
          git switch -c "$branch"
          git add -A
          git commit -m "ci(release): update version to $next, archive release notes"
          git push origin "$branch"

          # create PR
          body='
          # Reset `develop` after release '$ver'

          Merge (do not squash) this pull request to bring `master` back into `develop`,
          set the development version to `'$next'`, and archive the `'$ver'` release notes.
          '
          gh pr create -B "develop" -H "$branch" --title "Post release $ver reset" --body "$body"