From fd951e431da3eedcdb2e6585ebbf8cc6e9d29dda Mon Sep 17 00:00:00 2001 From: Bonelli Date: Tue, 10 Feb 2026 10:11:11 -0500 Subject: [PATCH] docs: update README and developer docs --- DEVELOPER.md | 76 +++++++++++++++++++++++++++------------------------- README.md | 6 +---- 2 files changed, 41 insertions(+), 41 deletions(-) diff --git a/DEVELOPER.md b/DEVELOPER.md index 1eeb920..ddec837 100644 --- a/DEVELOPER.md +++ b/DEVELOPER.md @@ -5,13 +5,15 @@ This document provides guidance for using this repository to release USGS execut + - [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) @@ -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: @@ -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 diff --git a/README.md b/README.md index 121f634..7ec9765 100644 --- a/README.md +++ b/README.md @@ -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