release.yml

name: Release
on:
  # start a release from the GitHub Actions UI (or `gh workflow run release.yml`)
  workflow_dispatch:
    inputs:
      branch:
        description: 'Branch to release from.'
        required: true
        type: string
        default: 'develop'
      version:
        description: "Version number to release, e.g. 1.9.3. Defaults to version.txt with its development suffix removed."
        required: false
        type: string
      run_tests:
        description: 'Run the test suite before drafting the release.'
        required: false
        type: boolean
        default: true
  push:
    branches:
      # a release can also be started by pushing a release branch
      - v[0-9]+.[0-9]+.[0-9]+*
      # merging the release branch drafts the release and publishes to PyPI
      - main
  release:
    types:
      - published
jobs:
  prep:
    name: Prepare release
    # runs on workflow_dispatch, or when a release branch is first pushed.
    # later pushes to the release branch must not prepare the release again.
    if: ${{ github.event_name == 'workflow_dispatch' || (github.event_name == 'push' && github.ref_name != 'main' && github.event.created) }}
    runs-on: ubuntu-latest
    permissions:
      contents: write
    outputs:
      version: ${{ steps.version.outputs.version }}
    defaults:
      run:
        shell: bash
    steps:

      - name: Check release branch
        if: ${{ github.event_name == 'workflow_dispatch' }}
        run: |
          if [[ "${{ inputs.branch }}" == "main" ]]; then
            echo "error: releases may not be started from main"
            exit 1
          fi

      - name: Checkout source branch
        uses: actions/checkout@v3
        with:
          ref: ${{ github.event_name == 'workflow_dispatch' && inputs.branch || github.ref_name }}
          fetch-depth: 0

      - name: Setup Python
        uses: actions/setup-python@v4
        with:
          python-version: 3.x
          cache: 'pip'
          cache-dependency-path: pyproject.toml

      - name: Install Python dependencies
        run: |
          pip install --upgrade pip
          pip install . --group test --group build twine

      - name: Resolve version
        id: version
        run: |
          if [[ "${{ github.event_name }}" == "workflow_dispatch" ]]; then
            if [[ -n "${{ inputs.version }}" ]]; then
              ver="${{ inputs.version }}"
            else
              ver=$(python scripts/update_version.py --release --dry-run)
            fi
          else
            # release branch name is the version number, prefixed with 'v'
            ref="${{ github.ref_name }}"
            ver="${ref#"v"}"
          fi
          echo "releasing version $ver"
          echo "version=$ver" >> $GITHUB_OUTPUT

      - name: Create release branch
        if: ${{ github.event_name == 'workflow_dispatch' }}
        run: git switch -c "v${{ steps.version.outputs.version }}"

      - name: Update version
        run: |
          python scripts/update_version.py -v "${{ steps.version.outputs.version }}"
          python -c "import modflow_devtools; print('Version: ', modflow_devtools.__version__)"

      - name: Touch changelog
        run: touch HISTORY.md

      - name: Generate changelog
        id: cliff
        uses: orhun/git-cliff-action@v1
        with:
          config: cliff.toml
          args: --verbose --unreleased --tag ${{ steps.version.outputs.version }}
        env:
          OUTPUT: CHANGELOG.md

      - name: Update changelog
        id: update-changelog
        run: |
          # move changelog
          clog="CHANGELOG_${{ steps.version.outputs.version }}.md"
          echo "changelog=$clog" >> $GITHUB_OUTPUT
          sudo cp "${{ steps.cliff.outputs.changelog }}" "$clog"
          
          # show current release changelog
          cat "$clog"
          
          # substitute full group names
          sed -i 's/#### Ci/#### Continuous integration/' "$clog"
          sed -i 's/#### Feat/#### New features/' "$clog"
          sed -i 's/#### Fix/#### Bug fixes/' "$clog"
          sed -i 's/#### Refactor/#### Refactoring/' "$clog"
          sed -i 's/#### Test/#### Testing/' "$clog"
          
          cat "$clog" HISTORY.md > temp_history.md
          sudo mv temp_history.md HISTORY.md
          
          # show full changelog
          cat HISTORY.md

      - name: Upload changelog
        uses: actions/upload-artifact@v4
        with:
          name: changelog
          path: ${{ steps.update-changelog.outputs.changelog }}

      - name: Push release branch
        run: |
          ver="${{ steps.version.outputs.version }}"

          # remove this release's changelog so we don't commit it
          # the changes have already been prepended to HISTORY.md
          rm ${{ steps.update-changelog.outputs.changelog }}
          rm -f CHANGELOG.md

          # commit and push changes
          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 add -A
          git commit -m "ci(release): set version to $ver, update changelog"
          git push origin "v$ver"

  test:
    name: Test release branch
    needs: prep
    if: ${{ github.event_name != 'workflow_dispatch' || inputs.run_tests }}
    permissions:
      contents: read
    uses: ./.github/workflows/ci.yml
    with:
      ref: v${{ needs.prep.outputs.version }}

  pr:
    name: Draft release pull request
    needs: [prep, test]
    if: ${{ always() && needs.prep.result == 'success' && (needs.test.result == 'success' || needs.test.result == 'skipped') }}
    runs-on: ubuntu-latest
    permissions:
      contents: read
      pull-requests: write
    defaults:
      run:
        shell: bash
    steps:

      - name: Checkout release branch
        uses: actions/checkout@v3
        with:
          ref: v${{ needs.prep.outputs.version }}

      - name: Download changelog
        uses: actions/download-artifact@v4
        with:
          name: changelog

      - name: Draft pull request
        env:
          GITHUB_TOKEN: ${{ github.token }}
        run: |
          ver="${{ needs.prep.outputs.version }}"
          changelog=$(grep -v "### Version $ver" "CHANGELOG_$ver.md")
          title="Release $ver"
          body='
          # Release '$ver'

          The release can be approved by merging this pull request into `main`. This will trigger a job to publish the release to PyPI.

          ## Changelog

          '$changelog'
          '
          gh pr create -B "main" -H "v$ver" --title "$title" --draft --body "$body"

  release:
    name: Draft release
    # runs only when changes are merged to main
    if: ${{ github.event_name == 'push' && github.ref_name == 'main' }}
    runs-on: ubuntu-latest
    permissions:
      contents: write
      pull-requests: write
    steps:

      - name: Checkout repo
        uses: actions/checkout@v3
        with:
          ref: main

      # actions/download-artifact won't look at previous workflow runs but we need to in order to get changelog
      - name: Download artifacts
        uses: dawidd6/action-download-artifact@v2

      - name: Draft release
        env:
          GITHUB_TOKEN: ${{ github.token }}
        run: |
          version=$(cat version.txt)
          title="MODFLOW developer tools $version"
          notes=$(cat "changelog/CHANGELOG_$version.md" | grep -v "### Version $version")
          gh release create "$version" \
            --target main \
            --title "$title" \
            --notes "$notes" \
            --draft \
            --latest

  publish:
    name: Publish package
    # runs only after release is published (manually promoted from draft)
    if: ${{ github.event_name == 'release' }}
    runs-on: ubuntu-22.04
    permissions:
      contents: write
      pull-requests: write
      id-token: write  # mandatory for trusted publishing
    environment:  # requires a 'release' environment in repo settings
      name: release
      url: https://pypi.org/p/modflow-devtools
    steps:

      - name: Checkout main branch
        uses: actions/checkout@v3
        with:
          ref: main

      - name: Setup Python
        uses: actions/setup-python@v4
        with:
          python-version: 3.x

      - name: Install Python dependencies
        run: |
          pip install --upgrade pip
          pip install build twine
          pip install .

      - name: Build package
        run: python -m build
      
      - name: Check package
        run: twine check --strict dist/*

      - name: Upload package
        uses: actions/upload-artifact@v4
        with:
          name: dist
          path: dist

      - name: Publish to PyPI
        uses: pypa/gh-action-pypi-publish@release/v1

  reset:
    name: Reset develop
    # runs after the release is published, opens a PR merging main back into develop
    needs: publish
    if: ${{ github.event_name == 'release' }}
    runs-on: ubuntu-latest
    permissions:
      contents: write
      pull-requests: write
    defaults:
      run:
        shell: bash
    steps:

      - name: Checkout main branch
        uses: actions/checkout@v3
        with:
          ref: main
          fetch-depth: 0

      - name: Setup Python
        uses: actions/setup-python@v4
        with:
          python-version: 3.x

      - name: Install Python dependencies
        run: |
          pip install --upgrade pip
          pip install filelock packaging

      - name: Open reset pull request
        env:
          GITHUB_TOKEN: ${{ github.token }}
        run: |
          ver=$(cat version.txt)
          branch="post-release-$ver-reset"

          # bump to the next minor version, with a '.devN' suffix where N is the
          # patch number of the version just released; prints the new version
          next=$(python scripts/update_version.py --post-release)

          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 version.txt modflow_devtools/__init__.py docs/conf.py
          git commit -m "ci(release): update version to $next"
          git push origin "$branch"

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

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