chore: split release notes into separate files

wpbonelli · wpbonelli · commit 1ff40777c06b · 2026-06-24T14:15:06.000-07:00
diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md
@@ -11,7 +11,7 @@ Checklist of items for pull request
 - [ ] Added doxygen comments to new and modified procedures
 - [ ] Updated meson files, makefiles, and Visual Studio project files for new source files
 - [ ] Updated [definition files](/MODFLOW-ORG/modflow6/tree/develop/doc/mf6io/mf6ivar)
-- [ ] Updated [develop.toml](/MODFLOW-ORG/modflow6/doc/ReleaseNotes/develop.toml) with a plain-language description of the bug fix, change, feature; required for changes that may affect users
+- [ ] Added a release note fragment to [doc/ReleaseNotes/changes/](/MODFLOW-ORG/modflow6/doc/ReleaseNotes/changes) with a plain-language description of the bug fix, change, or feature; required for changes that may affect users
 - [ ] Updated [input and output guide](/MODFLOW-ORG/modflow6/doc/mf6io)
 - [ ] Removed checklist items not relevant to this pull request
 
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -66,11 +66,17 @@ To submit a pull request (PR):
 
 1. To avoid duplicating effort, [search](https://github.com/MODFLOW-ORG/modflow6/pulls) for an open or closed PR that relates to your submission.
 2. Fork the MODFLOW-ORG/modflow6 repo and make your changes in a new branch, following our style and commit message guidelines and [including appropriate test cases](./DEVELOPER.md#writing-tests).
-3. [Check the spelling and formatting](./DEVELOPER.md#formatting) of any modified or new Fortran source files, python files definition files, markdown, and LaTeX files.
-4. [Rebuild makefiles](./DEVELOPER.md#generating-makefiles) and update MSVS project files if you added, removed, or renamed any source files.
-5. [Run the full test suite](./DEVELOPER.md#running-tests) and make sure all tests pass.
-6. Push your branch to GitHub and create a pull request to the `develop` branch.
-7. If we suggest changes:
+3. For user-facing changes (new features, bug fixes, behavior changes), add a release note fragment to `doc/ReleaseNotes/changes/`. Name the file with a short descriptive slug, e.g. `wel-auto-flow-reduce-auxname.toml`. Each fragment is a TOML file with three keys:
+   ```toml
+   section = "features"       # or "fixes" or "examples"
+   subsection = "stress"      # see [subsections] in doc/ReleaseNotes/schema.toml for valid values
+   description = "Description of the change..."
+   ```
+4. [Check the spelling and formatting](./DEVELOPER.md#formatting) of any modified or new Fortran source files, python files definition files, markdown, and LaTeX files.
+5. [Rebuild makefiles](./DEVELOPER.md#generating-makefiles) and update MSVS project files if you added, removed, or renamed any source files.
+6. [Run the full test suite](./DEVELOPER.md#running-tests) and make sure all tests pass.
+7. Push your branch to GitHub and create a pull request to the `develop` branch.
+8. If we suggest changes:
   a. make the required updates
   b. make sure tests still pass
   c. rebase your branch if needed
diff --git a/DEVELOPER.md b/DEVELOPER.md
@@ -957,8 +957,8 @@ This process can be repeated periodically to stay in sync with the develop branc
 
 To deprecate a MODFLOW 6 input/output option in a DFN file:
 
-- Add a new `deprecated x.y.z` attribute to the appropriate variable in the package DFN file, where `x.y.z` is the version the deprecation is introduced. Mention the deprecation prominently in the release notes.
-- If support for the deprecated option is removed (typically after at least 2 minor or major releases or 1 year), add a new `removed x.y.z` attribute to the variable in the DFN file, where `x.y.z` is the version in which support for the option was removed. The line containing `deprecated x.y.z` should not be deleted. Mention the removal prominently in the release notes.
+- Add a new `deprecated x.y.z` attribute to the appropriate variable in the package DFN file, where `x.y.z` is the version the deprecation is introduced. Mention the deprecation prominently in the release notes by adding a fragment to `doc/ReleaseNotes/changes/`.
+- If support for the deprecated option is removed (typically after at least 2 minor or major releases or 1 year), add a new `removed x.y.z` attribute to the variable in the DFN file, where `x.y.z` is the version in which support for the option was removed. The line containing `deprecated x.y.z` should not be deleted. Mention the removal prominently in the release notes by adding a fragment to `doc/ReleaseNotes/changes/`.
 - Deprecated/removed attributes are not removed from DFN files but remain in perpetuity. The `doc/mf6io/mf6ivar/deprecations.py` script generates a markdown deprecation table which is converted to LaTeX by `doc/ReleaseNotes/mk_deprecations.py` for inclusion in the MODFLOW 6 release notes. Deprecations and removals should still be mentioned separately in the release notes, however.
 
 ### Finding deprecations
diff --git a/distribution/README.md b/distribution/README.md
@@ -141,9 +141,9 @@ Before proceeding with a release, check for deprecated DFN variables due for rem
 
 ### Review release notes
 
-Double-check release notes in `doc/ReleaseNotes/develop.toml` with the authors of any changes to be included in the release.
+Double-check release notes in `doc/ReleaseNotes/changes/` with the authors of any changes to be included in the release. Each file in that directory is one release note item.
 
-For hotfix releases, `develop.toml` must be trimmed manually on the release branch. For patch releases made from `develop`, release notes are automatically filtered to include only fixes.
+For hotfix releases, fragment files for features not included in the hotfix must be removed manually on the release branch. For patch releases made from `develop`, release notes are automatically filtered to include only fixes.
 
 **Note**: For all releases, add a line to the Release History section of `ReleaseNotes.tex` providing the version number, date and DOI of the release, e.g. `6.4.4 & February 13, 2024 & \url{https://doi.org/10.5066/P9FL1JCC}`. DOIs are updated with minor releases and remain the same for patch releases.
 
@@ -209,15 +209,15 @@ This will substitute the new version number into the necessary files and set `ID
 
 #### Update release notes
 
-Generate a `develop.tex` file from `develop.toml`:
+Generate a `develop.tex` file from the release note fragments:
 
 ```shell
 pixi run make-release-notes
 ```
 
 Move/rename it to `doc/ReleaseNotes/previous/vx.y.z.tex` (where `x.y.z` is the version just released), then insert a new line `\input{./previous/vx.y.z.tex}` at the top of `doc/ReleaseNotes/appendixA.tex`.
 
-If this was not a hotfix, trim `doc/ReleaseNotes/develop.toml` as necessary to remove items just released.
+Delete all fragment files in `doc/ReleaseNotes/changes/` that were included in the release. The `.gitkeep` file should remain so the directory is tracked by git.
 
 Create and merge (don't squash) a pull request from this branch into `develop`.
 
diff --git a/distribution/build_docs.py b/distribution/build_docs.py
@@ -140,7 +140,7 @@ def build_notes_tex(force: bool = False, patch: bool = False):
 
     build_deprecations_tex(force=force)
 
-    toml_path = RELEASE_NOTES_PATH / "develop.toml"
+    toml_path = RELEASE_NOTES_PATH / "schema.toml"
     tex_path = RELEASE_NOTES_PATH / "develop.tex"
     if tex_path.is_file() and not force:
         print(f"{tex_path} already exists.")
diff --git a/doc/ReleaseNotes/changes/.gitkeep b/doc/ReleaseNotes/changes/.gitkeep
diff --git a/doc/ReleaseNotes/changes/README.md b/doc/ReleaseNotes/changes/README.md
@@ -0,0 +1,17 @@
+# Release notes
+
+Add files to this directory to describe user-facing changes (bug fixes, new features, new examples, etc) to be included in the next release of MODFLOW 6.
+
+To add a release note, create a `.toml` file with a short descriptive name, e.g. `wel-auto-flow-reduce-auxname.toml`:
+
+```toml
+section = "fixes"
+subsection = "stress"
+description = "Plain-language description of the change..."
+```
+
+Valid values for `section` and `subsection` are defined in `doc/ReleaseNotes/schema.toml`.
+
+Files are merged by the `mk_releasenotes.py` script underlying the `pixi run make-release-notes` task.
+
+Delete all fragment files included in the release. This directory should be empty (aside from this README) after the post-release reset.
diff --git a/doc/ReleaseNotes/changes/ats-parallel-gwt-gwe.toml b/doc/ReleaseNotes/changes/ats-parallel-gwt-gwe.toml
@@ -0,0 +1,3 @@
+section = "fixes"
+subsection = "parallel"
+description = "The adaptive time stepping algorithm (ATS) was not working correctly in parallel mode. This applies to GWT and GWE models, when the model time step derived from the ATS\\_PERCEL parameter is not uniform across processes. In such a case, a deadlock occurred and the simulation was stalled. This fix ensures that the actual calculation time steps are synchronized across all processes such that they remain in lockstep."
diff --git a/doc/ReleaseNotes/changes/bmi-get-grid-model-type-prt.toml b/doc/ReleaseNotes/changes/bmi-get-grid-model-type-prt.toml
@@ -0,0 +1,3 @@
+section = "fixes"
+subsection = "basic"
+description = "The BMI interface's get\\_grid\\_model\\_type function worked only for numerical model types such as GWF, GWT, and GWE, but would crash for PRT models. Fix the function's implementation to work with all model types."
diff --git a/doc/ReleaseNotes/changes/dis-missing-package-error.toml b/doc/ReleaseNotes/changes/dis-missing-package-error.toml
@@ -0,0 +1,3 @@
+section = "fixes"
+subsection = "basic"
+description = "Stop with an informative error if a discretization package is missing after loading the model input file's PACKAGES block."
diff --git a/doc/ReleaseNotes/changes/fmi-tdis-last-stress-period-check.toml b/doc/ReleaseNotes/changes/fmi-tdis-last-stress-period-check.toml
@@ -0,0 +1,3 @@
+section = "fixes"
+subsection = "model"
+description = "The Flow Model Interface (FMI) package for transport and tracking models conducts TDIS compatibility checks during each stress period to ensure that the model's time discretization is compatible with that of the flow model. In particular, if a flow model stress period has just one time step, the transport or tracking model may have any number of time steps. However, if a flow model stress period has more than one time step, the transport or tracking model must have the same number of time steps. Simulations would previously stop with an error if the transport or tracking model violated this rule for any stress periods up to the simulation's last, but would not raise an error for the last stress period. The compatibility check was updated to include the last stress period. Simulations will now stop with an error if the transport or tracking model violates this rule for any stress period in the simulation."
diff --git a/doc/ReleaseNotes/changes/gwf-gwf-mvr-gwt-gwt-no-mvt.toml b/doc/ReleaseNotes/changes/gwf-gwf-mvr-gwt-gwt-no-mvt.toml
@@ -0,0 +1,3 @@
+section = "fixes"
+subsection = "exchanges"
+description = "Avoids an unhandled and unnecessary exception in cases where a GWF-GWF exchange is configured with a MVR package, but the corresponding GWT-GWT exchange does not have a MVT package enabled."
diff --git a/doc/ReleaseNotes/changes/gwf-option-defaults.toml b/doc/ReleaseNotes/changes/gwf-option-defaults.toml
@@ -0,0 +1,3 @@
+section = "fixes"
+subsection = "stress"
+description = "The default values for DENSITY\\_WATER, HEAT\\_CAPACITY\\_WATER, LATENT\\_HEAT\\_VAPORIZATION specified in the OPTIONS block were not set as indicated in the MF6IO guide.  Defaults for these three variables now set as documented in the MF6IO guide."
diff --git a/doc/ReleaseNotes/changes/gwf-output-multiple-coupled-models.toml b/doc/ReleaseNotes/changes/gwf-output-multiple-coupled-models.toml
@@ -0,0 +1,3 @@
+section = "fixes"
+subsection = "basic"
+description = "Previously, GWF model output files could only be referenced by a single coupled model's FMI package. This might be necessary for certain configurations where multiple transport models or particle tracking models in the same simulation need flow information from a previous GWF simulation. Referencing the same GWF output files from multiple coupled models would cause a crash. Fix file-opening logic to allow multiple coupled models to refer to the same GWF model's output files."
diff --git a/doc/ReleaseNotes/changes/gwt-central-utvd-mass-balance.toml b/doc/ReleaseNotes/changes/gwt-central-utvd-mass-balance.toml
@@ -0,0 +1,3 @@
+section = "fixes"
+subsection = "internal"
+description = "Resolved mass-balance errors in the Central and UTVD numerical schemes caused by inconsistent interpretation of cell-to-interface distances (cl1/cl2)."
diff --git a/doc/ReleaseNotes/changes/hfb-disu-idomain-adjacency-check.toml b/doc/ReleaseNotes/changes/hfb-disu-idomain-adjacency-check.toml
@@ -0,0 +1,3 @@
+section = "fixes"
+subsection = "internal"
+description = "When a horizontal flow barrier is placed between two cells, MODFLOW checks to ensure that the cells are adjacent.  This check did not function correctly for DISU grids, in some cases, if the IDOMAIN functionality was used to remove cells.  The check for two adjacent DISU cells was corrected to work for IDOMAIN functionality."
diff --git a/doc/ReleaseNotes/changes/maw-non-vertical-wells.toml b/doc/ReleaseNotes/changes/maw-non-vertical-wells.toml
@@ -0,0 +1,3 @@
+section = "features"
+subsection = "advanced"
+description = "The Multi-Aquifer Well (MAW) Package now supports non-vertical (slanted or horizontal) well connections. When the NON\\_VERTICAL\\_WELLS option is specified, an ANGLEDATA block can be used to assign a tilt angle (deviation from vertical) to individual well connections. The saturated conductance for those connections is scaled by the in-cell screen length, which is calculated from the screen top, screen bottom, well radius, and tilt angle (or specified directly with an optional connection length), instead of the vertical screen thickness. A connection length must be specified for horizontal connections, and the MEAN conductance equation is recommended for horizontal connections."
diff --git a/doc/ReleaseNotes/changes/mvr-exchange-model-name-check.toml b/doc/ReleaseNotes/changes/mvr-exchange-model-name-check.toml
@@ -0,0 +1,3 @@
+section = "fixes"
+subsection = "exchanges"
+description = "When a MVR connection was included as part of an exchange between two models, it was possible to list a model name in the PACKAGES block of the MVR input file that is not one of the two models included in the exchange.  A check was added that reports an error message stating that a model name listed in the exchange MVR input file is not one of the two models connected by the exchange."
diff --git a/doc/ReleaseNotes/changes/mvr-parallel-gwt-gwe.toml b/doc/ReleaseNotes/changes/mvr-parallel-gwt-gwe.toml
@@ -0,0 +1,3 @@
+section = "fixes"
+subsection = "parallel"
+description = "Mover (MVR) Package connections across two or more models running in parallel were previously supported for flow but not for solute or energy transport.  GWT-GWT or GWE-GWE exchanges that also include MVT or MVE connections, respectively, is now supported for simulations run in parallel mode."
diff --git a/doc/ReleaseNotes/changes/netcdf-rcha-evta-index.toml b/doc/ReleaseNotes/changes/netcdf-rcha-evta-index.toml
@@ -0,0 +1,3 @@
+section = "fixes"
+subsection = "netcdf"
+description = "Fix an indexing issue in structured NetCDF export where READASARRAYS packages (RCHA, EVTA) with time-varying per-period arrays would crash with a NetCDF edge-exceeds-bound error when writing any stress period after the first."
diff --git a/doc/ReleaseNotes/changes/prt-ats-discarded-timestep-output.toml b/doc/ReleaseNotes/changes/prt-ats-discarded-timestep-output.toml
@@ -0,0 +1,3 @@
+section = "fixes"
+subsection = "model"
+description = "A PRT model coupled by an exchange to a GWF model that uses adaptive time stepping (ATS) would erroneously produce output for discarded/retried time step solve attempts. PRT output would also be erroneously produced for discarded Picard iterations. This has been fixed such that PRT will only produce output for successful solve attempts when used with an ATS flow model, and only for the final Picard iteration when MXITER > 1."
diff --git a/doc/ReleaseNotes/changes/prt-default-release-behavior.toml b/doc/ReleaseNotes/changes/prt-default-release-behavior.toml
@@ -0,0 +1,3 @@
+section = "fixes"
+subsection = "model"
+description = "PRT was described as configuring a single release at the beginning of the simulation by default, but a release was in fact scheduled for the first time step of every stress period. Fix the default release behavior so a single release occurs at the beginning of the simulation."
diff --git a/doc/ReleaseNotes/changes/prt-event-buffering.toml b/doc/ReleaseNotes/changes/prt-event-buffering.toml
@@ -0,0 +1,3 @@
+section = "features"
+subsection = "model"
+description = "Previously PRT model particle events were written to output file(s) immediately. By default, PRT will now buffer events in memory before writing them to disk. Introduce a new option for the PRT Output Control (OC) package, SCRATCH\\_BUFFER, which enables buffering events in scratch files instead of memory. This can avoid out-of-memory errors at the price of increased file IO and runtime."
diff --git a/doc/ReleaseNotes/changes/prt-local-z-icelltype-requirement.toml b/doc/ReleaseNotes/changes/prt-local-z-icelltype-requirement.toml
@@ -0,0 +1,3 @@
+section = "fixes"
+subsection = "model"
+description = "In MF6.7.0, the PRT model began to require binary grid (GRB) files provided to the Flow Model Interface (FMI) package to contain ICELLTYPE when any Particle Release Point (PRP) package used LOCAL\\_Z release coordinates, so PRT could distinguish confined from convertible cells when converting local z to model z coordinates. This requirement is unnecessary and has been removed. A single formula $z = bot + localz \\cdot sat \\cdot (top - bot)$ works correctly for both cell types, since $sat = 1$ for confined cells, and for convertible cells $sat = (head - bot) / (top - bot)$ clamped to $[0, 1]$. Particle z coordinates near the cell top or bottom may differ slightly from before, since saturation is smoothed near the top and bottom."
diff --git a/doc/ReleaseNotes/changes/prt-prp-drape-behavior.toml b/doc/ReleaseNotes/changes/prt-prp-drape-behavior.toml
@@ -0,0 +1,3 @@
+section = "fixes"
+subsection = "model"
+description = "Fix the PRT PRP package's DRAPE option's behavior. A draped particle's release was previously reported in the original release position, followed by a DROPPED (ireason=6) event due to the particle reaching the water table at tracking time as a result of the default DRY\\_TRACKING\\_METHOD setting DROP. This is inconsistent with the intent of the DRAPE option: DRAPE is applied before release to control a particle's release position. Draped particles will now be released in the highest active cell, at the water table if the cell is convertible or at the geometric top if the cell is confined, and no DROPPED event will be reported."
diff --git a/doc/ReleaseNotes/changes/rcha-evta-auxvar-reset-revert.toml b/doc/ReleaseNotes/changes/rcha-evta-auxvar-reset-revert.toml
@@ -0,0 +1,3 @@
+section = "fixes"
+subsection = "stress"
+description = "Reverts a 6.4.3 change that reset auxiliary variable arrays to zero each stress period in READASARRAYS packages (RCHA, EVTA). The earlier change had the consequence of zeroing the AUXMULTNAME multiplier array when not re-specified in a period block, effectively eliminating recharge or ET in subsequent stress periods. This behavior now is consistent across Grid Array and Layer Array package types. GWF models that use RCHA or EVTA and the AUXMULTNAME option may give different answers depending on how auxiliary variables were specified."
diff --git a/doc/ReleaseNotes/changes/readarraygrid-chd-wel-drn-riv-ghb.toml b/doc/ReleaseNotes/changes/readarraygrid-chd-wel-drn-riv-ghb.toml
@@ -0,0 +1,3 @@
+section = "features"
+subsection = "stress"
+description = "Grid array-based input (READARRAYGRID) is now available for the CHD, WEL, DRN, RIV, and GHB stress packages.  Grid array-based input allows stress package data to be specified as full-grid arrays using the DNODATA value (3.0E+30) to identify inactive cells.  Auxiliary variable arrays persist across stress periods if not re-specified, and CONSTANT array input is supported for any array after the first in a period block."
diff --git a/doc/ReleaseNotes/changes/wel-auto-flow-reduce-auxname.toml b/doc/ReleaseNotes/changes/wel-auto-flow-reduce-auxname.toml
@@ -0,0 +1,3 @@
+section = "features"
+subsection = "stress"
+description = "Added a new AUTO\\_FLOW\\_REDUCE\\_AUXNAME option to the Well (WEL) Package. When AUTO\\_FLOW\\_REDUCE is active, the pumping rate of a well is smoothly reduced as the cell head drops toward the cell bottom, using a single global turnoff threshold for all wells in the package. The new AUTO\\_FLOW\\_REDUCE\\_AUXNAME option names an auxiliary variable whose value sets the turnoff threshold for each well individually, so different wells in the same package can begin reducing their pumping at different heads. The per-well auxiliary value overrides the global AUTO\\_FLOW\\_REDUCE value and is interpreted the same way: as a length above the cell bottom when FLOW\\_REDUCTION\\_LENGTH is specified, or otherwise as a fraction of the cell thickness. If AUTO\\_FLOW\\_REDUCE\\_AUXNAME is specified without AUTO\\_FLOW\\_REDUCE the option is ignored with a warning, and an error is reported if the named auxiliary variable does not exist."
diff --git a/doc/ReleaseNotes/changes/wel-auto-flow-reduce-newton-linearization.toml b/doc/ReleaseNotes/changes/wel-auto-flow-reduce-newton-linearization.toml
@@ -0,0 +1,3 @@
+section = "fixes"
+subsection = "stress"
+description = "For the Well (WEL) Package, when AUTO\\_FLOW\\_REDUCE is active and FLOW\\_REDUCTION\\_LENGTH is specified, the Newton-Raphson linearization incorrectly used the cell thickness instead of the unit length (1.0) when computing the turnoff threshold. This produced an incorrect Jacobian term and inconsistent behavior between the standard and Newton formulations. The thickness calculation in the Newton code path now respects the FLOW\\_REDUCTION\\_LENGTH option, consistent with the non-Newton code path."
diff --git a/doc/ReleaseNotes/develop.toml b/doc/ReleaseNotes/develop.toml
diff --git a/doc/ReleaseNotes/mk_releasenotes.py b/doc/ReleaseNotes/mk_releasenotes.py
diff --git a/doc/ReleaseNotes/schema.toml b/doc/ReleaseNotes/schema.toml

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,3 @@`
	`1`	`+section = "fixes"`
	`2`	`+subsection = "parallel"`
	`3`	`+description = "The adaptive time stepping algorithm (ATS) was not working correctly in parallel mode. This applies to GWT and GWE models, when the model time step derived from the ATS\\_PERCEL parameter is not uniform across processes. In such a case, a deadlock occurred and the simulation was stalled. This fix ensures that the actual calculation time steps are synchronized across all processes such that they remain in lockstep."`
Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,3 @@`
	`1`	`+section = "fixes"`
	`2`	`+subsection = "basic"`
	`3`	`+description = "The BMI interface's get\\_grid\\_model\\_type function worked only for numerical model types such as GWF, GWT, and GWE, but would crash for PRT models. Fix the function's implementation to work with all model types."`