wpbonelli · Nov 1, 2026 · Sep 3, 2026 · Sep 3, 2026 · Sep 3, 2026 · Sep 3, 2026
diff --git a/.docs/md/get_modflow.md b/.docs/md/get_modflow.md
@@ -82,10 +82,10 @@ By default the distribution from the [`MODFLOW-ORG/executables` repository](http
 - `zbud6`
 - `libmf6.dylib`
 
-To select a distribution, specify a repository name with the `--repo` command line option or the `repo` function argument. Valid names are:
+To select a distribution, specify a repository name with the `--repo` command line option or the `repo` function argument. The official repositories are:
 
 - `executables` (default)
 - `modflow6`
 - `modflow6-nightly-build`
 
-The repository owner can also be configured with the `--owner` option. This can be useful for installing from unreleased MODFLOW 6 feature branches still in development &mdash; the only compatibility requirement is that release assets be named identically to those on the official repositories.
+The repository owner can also be configured with the `--owner` option. Together with `--repo`, this can be used to install from any repository, such as one that builds an unreleased MODFLOW 6 feature branch still in development &mdash; the only compatibility requirement is that release assets be named like those on the official repositories, with the operating system tag (e.g. `linux.zip`, `mac.zip`, `macarm.zip`, or `win64.zip`).
diff --git a/.docs/md/version_changes.md b/.docs/md/version_changes.md
diff --git a/.github/workflows/benchmark.yml b/.github/workflows/benchmark.yml
@@ -12,7 +12,7 @@ jobs:
       fail-fast: false
       matrix:
         os: [ ubuntu-latest, macos-latest, windows-latest ]
-        python-version: [ "3.11", "3.12", "3.13", "3.14" ]
+        python-version: [ "3.12", "3.13", "3.14" ]
     defaults:
       run:
         shell: bash -l {0}
@@ -82,6 +82,7 @@ jobs:
       - name: Setup Python
         uses: astral-sh/setup-uv@v7
         with:
+          python-version: "3.12"
           cache-dependency-glob: "**/pyproject.toml"
 
       - name: Install FloPy

diff --git a/.github/workflows/codegen.yml b/.github/workflows/codegen.yml
@@ -13,7 +13,7 @@ jobs:
       fail-fast: false
       matrix:
         os: [ ubuntu-latest, macos-latest, windows-latest ]
-        python-version: [ "3.11", "3.11", "3.12", "3.13", "3.14" ]
+        python-version: [ "3.12", "3.13", "3.14" ]
         ref: ["develop", "master", "6.4.1", "6.4.0"]
     defaults:
       run:

diff --git a/.github/workflows/commit.yml b/.github/workflows/commit.yml
@@ -71,7 +71,7 @@ jobs:
         shell: bash
     timeout-minutes: 10
     env:
-      PYTHON_VERSION: '3.11'
+      PYTHON_VERSION: '3.12'
 
     steps:
       - name: Checkout repo
@@ -80,6 +80,7 @@ jobs:
       - name: Setup Python
         uses: astral-sh/setup-uv@v7
         with:
+          python-version: ${{ env.PYTHON_VERSION }}
           cache-dependency-glob: "**/pyproject.toml"
 
       - name: Install Python dependencies
@@ -115,7 +116,7 @@ jobs:
       fail-fast: false
       matrix:
         os: [ ubuntu-latest, macos-latest, windows-latest ]
-        python-version: [ "3.11", "3.12", "3.13", "3.14" ]
+        python-version: [ "3.12", "3.13", "3.14" ]
     defaults:
       run:
         shell: bash -l {0}
@@ -150,9 +151,9 @@ jobs:
           version: 13
 
       - name: Setup pixi
-        uses: prefix-dev/setup-pixi@v0.10.2
+        uses: prefix-dev/setup-pixi@v0.11.2
         with:
-          pixi-version: v0.70.1
+          pixi-version: v0.82.1
           manifest-path: modflow6/pixi.toml
 
       - name: Install dependencies

diff --git a/.github/workflows/examples.yml b/.github/workflows/examples.yml
@@ -12,7 +12,7 @@ jobs:
       fail-fast: false
       matrix:
         os: [ ubuntu-latest, macos-latest, windows-latest ]
-        python-version: [ "3.11", "3.12", "3.13", "3.14" ]
+        python-version: [ "3.12", "3.13", "3.14" ]
     defaults:
       run:
         shell: bash
@@ -30,12 +30,9 @@ jobs:
       - name: Install FloPy
         run: uv sync --all-extras
 
-      - name: OpenGL workaround on Linux
+      - name: Set up headless display on Linux
         if: runner.os == 'Linux'
-        run: |
-          # referenced from https://github.com/pyvista/pyvista/blob/main/.github/workflows/vtk-pre-test.yml#L53
-          uv pip uninstall vtk
-          uv pip install --extra-index-url https://wheels.vtk.org trame vtk-osmesa
+        uses: pyvista/setup-headless-display-action@v5
 
       - name: Install OpenGL on Windows
         if: runner.os == 'Windows'

diff --git a/.github/workflows/mf6.yml b/.github/workflows/mf6.yml
@@ -39,9 +39,9 @@ jobs:
         version: 13
 
     - name: Setup pixi
-      uses: prefix-dev/setup-pixi@v0.10.2
+      uses: prefix-dev/setup-pixi@v0.11.2
       with:
-        pixi-version: v0.70.1
+        pixi-version: v0.82.1
         manifest-path: modflow6/pixi.toml
 
     - name: Install dependencies
@@ -122,9 +122,9 @@ jobs:
         version: 13
 
     - name: Setup pixi
-      uses: prefix-dev/setup-pixi@v0.10.2
+      uses: prefix-dev/setup-pixi@v0.11.2
       with:
-        pixi-version: v0.70.1
+        pixi-version: v0.82.1
         manifest-path: modflow6/pixi.toml
 
     - name: Install dependencies

diff --git a/.github/workflows/optional.yml b/.github/workflows/optional.yml
@@ -15,7 +15,7 @@ jobs:
         shell: bash
     timeout-minutes: 10
     env:
-      PYTHON_VERSION: '3.11'
+      PYTHON_VERSION: '3.12'
     strategy:
       fail-fast: false
       matrix:
@@ -31,6 +31,7 @@ jobs:
       - name: Setup Python
         uses: astral-sh/setup-uv@v7
         with:
+          python-version: ${{ env.PYTHON_VERSION }}
           cache-dependency-glob: "**/pyproject.toml"
 
       - name: Install FloPy without optional dependencies

diff --git a/.github/workflows/pull_request.yml b/.github/workflows/pull_request.yml
@@ -0,0 +1,43 @@
+name: pull request
+
+on:
+  pull_request:
+    types: [opened, edited, reopened, synchronize]
+    branches: [develop]
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+jobs:
+
+  title:
+    name: check title
+    # the release and reset pull requests are opened by a bot and are not
+    # squash merged, so their titles do not reach the changelog
+    if: github.event.pull_request.user.type != 'Bot'
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        shell: bash
+    steps:
+
+      - name: Check conventional commit format
+        env:
+          TITLE: ${{ github.event.pull_request.title }}
+        run: |
+          # pull requests are squash merged, so the title becomes the commit
+          # message in develop, and the changelog is generated from those
+          # messages. a title that is not a conventional commit is dropped
+          # from the release notes without warning.
+          types="build|chore|ci|docs|feat|fix|perf|refactor|revert|style|test"
+          if [[ ! "$TITLE" =~ ^($types)(\([^\)]+\))?!?:\ .+ ]]; then
+            echo "::error::'$TITLE' is not a conventional commit header."
+            echo ""
+            echo "Use '<type>(<scope>): <subject>', for example:"
+            echo "  feat(mf6): support adaptive time step retries"
+            echo ""
+            echo "Type is one of: ${types//|/, }."
+            echo "Only feat, fix, perf and refactor reach the release notes;"
+            echo "see cliff.toml. A user facing change needs one of those."
+            exit 1
+          fi
+          echo "'$TITLE' is a conventional commit header"
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
@@ -27,6 +27,7 @@ jobs:
       - name: Setup Python
         uses: astral-sh/setup-uv@v7
         with:
+          python-version: "3.12"
           enable-cache: false
 
       - name: Install FloPy
@@ -175,7 +176,7 @@ jobs:
 
       # 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@v24
+        uses: dawidd6/action-download-artifact@v27
 
       - name: Draft release
         env:
@@ -213,6 +214,7 @@ jobs:
       - name: Setup Python
         uses: astral-sh/setup-uv@v7
         with:
+          python-version: "3.12"
           enable-cache: false
 
       - name: Build package
@@ -223,3 +225,67 @@ jobs:
 
       - name: Publish package
         run: uv publish --verbose --trusted-publishing always
+
+  reset:
+    name: Draft develop reset PR
+    # runs after a release is published, opens a PR merging master back into develop
+    if: ${{ github.event_name == 'release' }}
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      pull-requests: write
+    defaults:
+      run:
+        shell: bash
+    steps:
+
+      - name: Checkout master branch
+        uses: actions/checkout@v7
+        with:
+          ref: master
+          fetch-depth: 0
+
+      - name: Setup Python
+        uses: astral-sh/setup-uv@v7
+        with:
+          python-version: "3.12"
+          enable-cache: false
+
+      - name: Install FloPy
+        run: uv sync --all-extras
+
+      - name: Update version numbers
+        id: version
+        run: |
+          ver=$(cat version.txt)
+          next=$(uv run scripts/update_version.py --post-release)
+          echo "version=$ver" >> $GITHUB_OUTPUT
+          echo "next=$next" >> $GITHUB_OUTPUT
+
+      - name: Format and lint Python files
+        run: |
+          uvx ruff format flopy/version.py
+          uvx ruff check --fix flopy/version.py
+
+      - name: Draft pull request
+        env:
+          GITHUB_TOKEN: ${{ github.token }}
+        run: |
+          ver="${{ steps.version.outputs.version }}"
+          next="${{ steps.version.outputs.next }}"
+          branch="post-release-$ver-reset"
+
+          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 flopy/version.py version.txt CITATION.cff README.md docs/PyPI_release.md
+          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 `master` back into `develop` and set the development version to `'$next'`.
+          '
+          gh pr create -B "develop" -H "$branch" --title "Reset develop after release $ver" --draft --body "$body"
diff --git a/.github/workflows/rtd.yml b/.github/workflows/rtd.yml
@@ -87,9 +87,9 @@ jobs:
           echo $GITHUB_EVENT_NAME
 
       - name: Setup pixi
-        uses: prefix-dev/setup-pixi@v0.10.2
+        uses: prefix-dev/setup-pixi@v0.11.2
         with:
-          pixi-version: v0.70.1
+          pixi-version: v0.82.1
           manifest-path: modflow6/pixi.toml
 
       - name: Install Python dependencies
@@ -98,14 +98,6 @@ jobs:
           pixi run -e rtd install
           pixi run -e rtd pip install "../flopy[optional]"
 
-      - name: Workaround OpenGL issue on Linux
-        if: runner.os == 'Linux'
-        working-directory: modflow6
-        run: |
-          # referenced from https://github.com/pyvista/pyvista/blob/main/.github/workflows/vtk-pre-test.yml#L53
-          pixi run -e rtd pip uninstall vtk
-          pixi run -e rtd pip install --extra-index-url https://wheels.vtk.org trame vtk-osmesa
-
       - name: Install fonts on Linux
         if: runner.os == 'Linux'
         run: |

diff --git a/.readthedocs.yml b/.readthedocs.yml
@@ -9,17 +9,20 @@ version: 2
 build:
   os: ubuntu-22.04
   tools:
-    python: "3.11"
-  # todo: uncomment below if notebooks are to be executed in RTD build
-  # instead of in CI as currently, requires runtime reduction <15 mins
-  # jobs:
-  #   post_create_environment:
-  #     # install MODFLOW6 and related executables (notebooks need them)
-  #     - get-modflow :python
-  #     # swap default vtk for vtk-osmesa (avoid PyVista openGL errors)
-  #     # https://github.com/pyvista/pyvista/blob/main/.github/workflows/vtk-pre-test.yml#L53
-  #     - pip uninstall -y vtk
-  #     - pip install --extra-index-url https://wheels.vtk.org trame vtk-osmesa
+    python: "3.12"
+  jobs:
+    install:
+      - pip install --upgrade "pip>=25.1"
+      - pip install --group docs .
+    # todo: uncomment below if notebooks are to be executed in RTD build
+    # instead of in CI as currently, requires runtime reduction <15 mins
+    # post_install:
+    #   # install MODFLOW6 and related executables (notebooks need them)
+    #   - get-modflow :python
+    #   # swap default vtk for vtk-osmesa (avoid PyVista openGL errors)
+    #   # https://github.com/pyvista/pyvista/blob/main/.github/workflows/vtk-pre-test.yml#L53
+    #   - pip uninstall -y vtk
+    #   - pip install --extra-index-url https://wheels.vtk.org trame vtk-osmesa
 
 # Build documentation in the docs/ directory with Sphinx
 sphinx:
@@ -28,11 +31,3 @@ sphinx:
 # Build only html and htmlzip (skip others, including PDF and EPUB)
 formats:
   - htmlzip
-
-# Set the Python version and requirements
-python:
-  install:
-    - method: pip
-      path: .
-      extra_requirements:
-        - doc
diff --git a/CITATION.cff b/CITATION.cff
@@ -3,8 +3,8 @@ message: If you use this software, please cite both the article from preferred-c
   references, and the software itself.
 type: software
 title: FloPy
-version: 3.11.0
-date-released: '2026-09-03'
+version: 3.12.0
+date-released: '2026-10-31'
 doi: 10.5066/F7BK19FH
 abstract: A Python package to create, run, and post-process MODFLOW-based models.
 repository-artifact: https://pypi.org/project/flopy

diff --git a/DEVELOPER.md b/DEVELOPER.md
@@ -33,6 +33,7 @@ This document describes how to set up a FloPy development environment, run the e
     - [Snapshot testing](#snapshot-testing)
   - [Branching model](#branching-model)
   - [Deprecation policy](#deprecation-policy)
+  - [Releasing](#releasing)
   - [Miscellaneous](#miscellaneous)
     - [Locating the root](#locating-the-root)
     - [Dependency analysis](#dependency-analysis)
@@ -60,9 +61,9 @@ git config blame.ignoreRevsFile .git-blame-ignore-revs
 
 ### Python
 
-This project has historically aimed to support a wide range of [Python versions](https://devguide.python.org/versions/). In current and future development this window may narrow to follow [SPEC 0](https://scientific-python.org/specs/spec-0000/#support-window) instead.
+This project has historically aimed to support a wide range of [Python versions](https://devguide.python.org/versions/). Development now follows the [SPEC 0](https://scientific-python.org/specs/spec-0000/#support-window) support window instead.
 
-Install Python >=3.11 via [standalone download](https://www.python.org/downloads/), [uv](https://docs.astral.sh/uv/), or a conda-like distribution like [Anaconda](https://www.anaconda.com/products/individual), [miniconda](https://docs.conda.io/en/latest/miniconda.html) or [miniforge](https://github.com/conda-forge/miniforge) .
+Install Python >=3.12 via [standalone download](https://www.python.org/downloads/), [uv](https://docs.astral.sh/uv/), or a conda-like distribution like [Anaconda](https://www.anaconda.com/products/individual), [miniconda](https://docs.conda.io/en/latest/miniconda.html) or [miniforge](https://github.com/conda-forge/miniforge) .
 
 Then install FloPy and core dependencies from the project root path:
 
@@ -459,6 +460,10 @@ This project loosely follows [NEP 23](https://numpy.org/neps/nep-0023-backwards-
 
 See the linked article for more detail.
 
+## Releasing
+
+The release procedure is documented separately in [docs/make_release.md](docs/make_release.md). FloPy releases are automated from a pushed `v<x.y.z>` branch, publish to PyPI with [trusted publishing](https://docs.pypi.org/trusted-publishers/) from a `release` environment, and reach conda-forge through the autotick bot. There are also a few manual steps (updating citations, reviewing deprecations, regenerating the MF6 module); see the release guide for the full sequence and the caveats.
+
 ## Miscellaneous
 
 ### Locating the root