Skip to content

docs: update README and developer docs #62

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
wpbonelli merged 1 commit into from
Feb 10, 2026
Merged

docs: update README and developer docs #62

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
76 changes: 40 additions & 36 deletions DEVELOPER.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,13 +5,15 @@ This document provides guidance for using this repository to release USGS execut
<!-- START doctoc generated TOC please keep comment here to allow auto update -->
<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->


- [Overview](#overview)
- [Program sources](#program-sources)
- [Hybrid release system](#hybrid-release-system)
- [How it works](#how-it-works)
- [Fetched from pre-built GitHub releases](#fetched-from-pre-built-github-releases)
- [Built from source by pymake](#built-from-source-by-pymake)
- [How it works](#how-it-works)
- [Adding a program](#adding-a-program)
- [Updating a version](#updating-a-version)
- [Future migration](#future-migration)
- [Updating a program](#updating-a-program)
- [Future `modflow-devtools` migration](#future-modflow-devtools-migration)
- [Triggering a release](#triggering-a-release)
- [GitHub UI](#github-ui)
- [GitHub CLI](#github-cli)
Expand Down Expand Up @@ -49,43 +51,41 @@ The distribution includes programs from across the MODFLOW ecosystem. Each progr

These programs are downloaded as pre-built binaries via `releases.json`. Their repositories publish platform-specific archives (linux.zip, mac.zip, macarm.zip, win64.zip) as release assets.

| Program(s) | Repository | Release tag | Notes |
|------------|-----------|-------------|-------|
| mf6, zbud6, libmf6 | [MODFLOW-ORG/modflow6](https://github.com/MODFLOW-ORG/modflow6) | 6.6.3 | Assets named `mf6.6.3_{platform}.zip`, binaries nested in `bin/` subdirectory |
| triangle | [MODFLOW-ORG/triangle](https://github.com/MODFLOW-ORG/triangle) | v1.6 | |
| gridgen | [MODFLOW-ORG/gridgen](https://github.com/MODFLOW-ORG/gridgen) | v1.0.02 | |
| zonbud | [MODFLOW-ORG/zonbud](https://github.com/MODFLOW-ORG/zonbud) | v3.01 | |
| zonbudusg | [MODFLOW-ORG/zonbudusg](https://github.com/MODFLOW-ORG/zonbudusg) | v1.01 | |
| mfusg_gsi | [MODFLOW-ORG/mfusgt](https://github.com/MODFLOW-ORG/mfusgt) | v2.6.0 | Archive contains `mfusgt`, renamed to `mfusg_gsi` |
| Program(s) | Repository | Release tag |
|------------|-----------|-------------|
| mf6, zbud6, mf5to6, libmf6 | [MODFLOW-ORG/modflow6](https://github.com/MODFLOW-ORG/modflow6) | 6.7.0 |
| triangle | [MODFLOW-ORG/triangle](https://github.com/MODFLOW-ORG/triangle) | v1.6 |
| gridgen | [MODFLOW-ORG/gridgen](https://github.com/MODFLOW-ORG/gridgen) | v1.0.02 |
| zonbud | [MODFLOW-ORG/zonbud](https://github.com/MODFLOW-ORG/zonbud) | v3.01 |
| zonbudusg | [MODFLOW-ORG/zonbudusg](https://github.com/MODFLOW-ORG/zonbudusg) | v1.01 |
| mfnwt, mfnwtdbl | [MODFLOW-ORG/mfnwt](https://github.com/MODFLOW-ORG/mfnwt) | v1.3.0 |
| swtv4 | [MODFLOW-ORG/swtv4](https://github.com/MODFLOW-ORG/swtv4) | v4.00.05 |
| mp6 | [MODFLOW-ORG/modpath6](https://github.com/MODFLOW-ORG/modpath6) | v6.0.1 |
| vs2dt | [MODFLOW-ORG/vs2dt](https://github.com/MODFLOW-ORG/vs2dt) | v3.3 |
| mflgr, mflgrdbl | [MODFLOW-ORG/mflgr](https://github.com/MODFLOW-ORG/mflgr) | v2.0.0 |
| mf2000 | [MODFLOW-ORG/mf2000](https://github.com/MODFLOW-ORG/mf2000) | v1.19.01 |

### Built from source by pymake

These programs are compiled by pymake because their repositories do not yet publish pre-built platform binaries.

| Program(s) | Source | Notes |
|------------|--------|-------|
| mf2005, mf2005dbl | [MODFLOW-ORG/mf2005](https://github.com/MODFLOW-ORG/mf2005) | Source-only release (v.1.12.00) |
| mfusg, mfusgdbl | [MODFLOW-ORG/mfusg](https://github.com/MODFLOW-ORG/mfusg) | Source-only release (v1.5.00) |
| mt3dms | [MODFLOW-ORG/mt3dms](https://github.com/MODFLOW-ORG/mt3dms) | Source-only release (2.0) |
| mt3dusgs | [MODFLOW-ORG/mt3d-usgs](https://github.com/MODFLOW-ORG/mt3d-usgs) | Source-only release (1.1.0) |
| mflgr, mflgrdbl | [USGS](https://water.usgs.gov/ogw/modflow-lgr/) | No GitHub repo |
| mfnwt, mfnwtdbl | [USGS](https://water.usgs.gov/water-resources/software/MODFLOW-NWT/) | No GitHub repo |
| mp6 | [USGS](https://water.usgs.gov/water-resources/software/MODPATH/) | No GitHub repo |
| mp7 | [USGS](https://water.usgs.gov/water-resources/software/MODPATH/) | [MODFLOW-ORG/modpath-v7](https://github.com/MODFLOW-ORG/modpath-v7) exists but has no releases |
| crt | [USGS](https://water.usgs.gov/ogw/CRT/) | No GitHub repo |
| vs2dt | [USGS](https://water.usgs.gov/water-resources/software/VS2DI/) | No GitHub repo |
| sutra | [USGS](https://water.usgs.gov/water-resources/software/sutra/) | No GitHub repo |
| mf2000 | [USGS](https://water.usgs.gov/nrp/gwsoftware/modflow2000/) | No GitHub repo |
| swtv4 | [USGS](https://water.usgs.gov/water-resources/software/SEAWAT/) | No GitHub repo |
These programs are compiled by pymake.

| Program(s) | Source |
|------------|--------|
| mf2005, mf2005dbl | [MODFLOW-ORG/mf2005](https://github.com/MODFLOW-ORG/mf2005) |
| mfusg, mfusgdbl | [MODFLOW-ORG/mfusg](https://github.com/MODFLOW-ORG/mfusg) |
| mfusg_gsi | [MODFLOW-ORG/mfusgt](https://github.com/MODFLOW-ORG/mfusgt) |
| mt3dms | [MODFLOW-ORG/mt3dms](https://github.com/MODFLOW-ORG/mt3dms) |
| mt3dusgs | [MODFLOW-ORG/mt3d-usgs](https://github.com/MODFLOW-ORG/mt3d-usgs) |
| mp7 | [USGS](https://water.usgs.gov/water-resources/software/MODPATH/) |
| crt | [USGS](https://water.usgs.gov/ogw/CRT/) |
| sutra | [USGS](https://water.usgs.gov/water-resources/software/sutra/) |

To move a program from "built by pymake" to "fetched from releases", its repository needs to start publishing platform-specific binary archives as GitHub release assets, then an entry can be added to `releases.json` (see [Adding a program](#adding-a-program)).

## Hybrid release system
## How it works

The release workflow uses a hybrid approach: some programs are downloaded as pre-built binaries from their independently managed GitHub repositories, while others are still compiled from source by pymake. This is a stopgap until the [modflow-devtools programs API](https://github.com/MODFLOW-ORG/modflow-devtools/issues/263) is ready to manage all program installations.

### How it works

The file `releases.json` in the repository root is a manifest listing programs to fetch from GitHub releases. Each entry specifies a source repository, release tag, platform-specific asset filenames, and a mapping of output program names to archive filenames.

During a release build, the workflow:
Expand Down Expand Up @@ -123,13 +123,17 @@ When a program repository begins publishing pre-built platform binaries as relea

The program will automatically be excluded from the pymake build. No workflow changes are needed.

### Updating a version
### Updating a program

To update a fetched program to a new release, change the `tag` field in its `releases.json` entry (and update asset filenames if they changed). The next release build will fetch the new version.

To update a program built by pymake, update the program database in the pymake repository.

To update a program to a new release, change the `tag` field in its `releases.json` entry (and update asset filenames if they changed). The next release build will fetch the new version.
### Future `modflow-devtools` migration

### Future migration
This hybrid system will be replaced by the [modflow-devtools programs API](https://github.com/MODFLOW-ORG/modflow-devtools/issues/263) once it is ready. At that point, `releases.json` and `scripts/fetch_releases.py` can be removed and replaced with a `programs install` command.

This hybrid system will be replaced by the [modflow-devtools programs API](https://github.com/MODFLOW-ORG/modflow-devtools/issues/263) once it is ready. The programs API uses a similar model (repository + tag + platform assets) but adds registry synchronization, caching, and multi-version management. At that point, `releases.json` and `scripts/fetch_releases.py` can be removed and replaced with a `programs install` command. When installation of the full suite is possible with devtools it is possible a combined distribution like this repository becomes less of a necessity but it becomes trivially maintainable.
When installation of the full suite is possible with devtools it is possible a combined distribution like this repository becomes less of a necessity, but it becomes trivially maintainable.

## Triggering a release

Expand Down
6 changes: 1 addition & 5 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,11 +2,7 @@

The purpose of this repository is to distribute binaries for MODFLOW and related programs. Distributions are provided for Windows, Mac, and Linux operating systems. Programs are compiled using [pymake](https://github.com/modflowpy/pymake) and Intel OneAPI compilers. The release also includes a json file [`code.json`](https://github.com/MODFLOW-ORG/executables/releases/latest/download/code.json) that includes, for each program, the current version number, the URL that can be used to download the source files, and the date sources were last updated. A markdown version of this file, `code.md` is also included in the distribution.

Executables for these different operating systems can be found under the [release](https://github.com/MODFLOW-ORG/executables/releases) tab above and are named:

* [win64.zip](https://github.com/MODFLOW-ORG/executables/releases/latest/download/win64.zip)
* [mac.zip](https://github.com/MODFLOW-ORG/executables/releases/latest/download/mac.zip)
* [linux.zip](https://github.com/MODFLOW-ORG/executables/releases/latest/download/linux.zip)
Distributions can be found under the [release](https://github.com/MODFLOW-ORG/executables/releases) tab.

The programs, version numbers, and the date stamp on the downloaded file used to create the executables for the present release are

Expand Down