ci(release): allow filtering notes for patch releases (#2523)

Add a --patch argument to the mk_releasenotes.py script which turns develop.toml into LaTeX. Add corresponding option to build_docs.py. This switch will omit everything but fixes from the release notes, suitable for a patch release.

(In future maybe consider a more specific LaTeX tag than \ifdevelop, indicating something is a new feature? Then --patch could omit those sections. Maybe --patch could also diff the DFNs and find/omit new options too, so we don't need to mark them with prerelease true. Just thinking ahead.)

Also restore a couple new feature items that got accidentally dropped recently

Author: wpbonelli

distribution/build_docs.py

@@ -132,7 +132,7 @@ def build_deprecations_tex(force: bool = False):
     assert tex_path.is_file()
 
 
-def build_notes_tex(force: bool = False):
+def build_notes_tex(force: bool = False, patch: bool = False):
     """Build LaTeX files for the release notes."""
 
     build_deprecations_tex(force=force)
@@ -144,14 +144,16 @@ def build_notes_tex(force: bool = False):
     else:
         tex_path.unlink(missing_ok=True)
         with set_dir(RELEASE_NOTES_PATH):
-            out, err, ret = run_py_script(
+            args = [
                 "mk_releasenotes.py",
                 "--toml",
                 toml_path,
                 "--tex",
                 tex_path,
-                verbose=True,
-            )
+            ]
+            if patch:
+                args.append("--patch")
+            out, err, ret = run_py_script(*args, verbose=True)
             assert not ret, out + err
 
     assert tex_path.is_file()
@@ -390,6 +392,7 @@ def build_documentation(
     models: Optional[list[str]] = None,
     repo_owner: str = "MODFLOW-ORG",
     developmode: bool = True,
+    patch: bool = False,
 ):
     """Build documentation for a MODFLOW 6 distribution."""
 
@@ -412,7 +415,7 @@ def build_documentation(
             workspace_path=Path(temp),
             example_model_path=PROJ_ROOT_PATH / ".mf6minsim",
         )
-        build_notes_tex(force=force)
+        build_notes_tex(force=force, patch=patch)
 
         if full:
             build_benchmark_tex(out_path=out_path, force=force)
@@ -508,15 +511,27 @@ def test_build_documentation(tmp_path):
         "--releasemode",
         required=False,
         action="store_true",
-        help="Omit prerelease variables from documentation "
-        "(defaults to false for development distributions)",
+        help="Omit prerelease variables/sections from documentation. "
+        "MF6IO variables marked 'prerelease' are omitted, as well as "
+        "LaTeX sections surrounded with '\\ifdevelopmode ... \\fi'. "
+        "Defaults to false.",
+    )
+    parser.add_argument(
+        "--patch",
+        default=False,
+        action="store_true",
+        help="Filter content from documentation for a patch release. "
+        "Include only items in the 'fixes' section in release notes; "
+        "that's all this does now, but in the future it may do more. "
+        "Defaults to false.",
     )
     args = parser.parse_args()
     output_path = Path(args.output_path).expanduser().absolute()
     output_path.mkdir(parents=True, exist_ok=True)
     bin_path = Path(args.bin_path).expanduser().absolute()
     models = args.model if args.model else DEFAULT_MODELS
     developmode = not args.releasemode
+    patch = args.patch
     build_documentation(
         bin_path=bin_path,
         out_path=output_path,
@@ -525,4 +540,5 @@ def test_build_documentation(tmp_path):
         models=models,
         repo_owner=args.repo_owner,
         developmode=developmode,
+        patch=patch,
     )

doc/ReleaseNotes/develop.toml

@@ -53,7 +53,7 @@ section = "fixes"
 subsection = "model"
 description = "Fixed ambiguous reporting of cell and subcell events by PRT on DISV grids. Previously subcell exit events and cell exit events were reported with the same event code (1). Subcell events are a tracking method implementation detail, however. Subcell events (and more generally, events occurring at subgrid scale) are no longer included by default in particle tracking output. The PRT Output Control (OC) package's TRACK\\_EXIT option now applies only to features explicitly defined by the grid discretization. Particle events at sub-grid scale are now opt-in with a new keyword option TRACK\\_SUBFEATURE\\_EXIT."
 
-[[item]]
+[[items]]
 section = "fixes"
 subsection = "model"
 description = "Fixed two infinite loop conditions in PRT models. First, cyclic paths were possible in the vicinity of assigned boundary faces. When an internal boundary face was assigned (an IFLOWFACE adjacent to another active cell), the adjacent cells could fail to agree on the flow through their shared face, trapping particles in an infinite loop. Particles now terminate at internal assigned boundary faces for which net boundary flow through the face is out of the cell. Particles continue to terminate at all external assigned boundary faces as before. Second, cyclic paths were possible near the water table with GWF models using the NEWTON option. With Newton, dry cells remain active; a flow model may produce numerically insignificant upwards flow through the top face of a partially saturated cell. With DRY\\_TRACKING\\_METHOD DROP (the default option), a particle in a partially saturated cell could obtain an exit solution through the cell's top face, jump to the dry cell above, then drop back down, and so on. In partially saturated cells, any flow upwards through the top face which is not associated with an assigned boundary is now ignored. This prevents particles from exiting through the top face of partially saturated cells unless the top face is an assigned boundary."
@@ -96,4 +96,14 @@ description = "Fixed a memory exception that has occurred when running parallel
 [[items]]
 section = "fixes"
 subsection = "parallel"
-description = "Fixed the case where a convergence failure of the PETSc linear solver halts the program with an exception (error -5). This particular failure is now handled by continuing with the next outer iteration. This is equivalent to what happens when using the IMS solver in a serial simulation."
+description = "Fixed the case where a convergence failure of the PETSc linear solver halts the program with an exception (error -5). This particular failure is now handled by continuing with the next outer iteration. This is equivalent to what happens when using the IMS solver in a serial simulation."
+
+[[items]]
+section = "features"
+subsection = "stress"
+description = "Added HIGHEST\\_SATURATED option to the GWT SRC package. When activated, the HIGHEST\\_SATURATED option will apply a mass source loading rate to the specified CELLID or the highest underlying cell with a non-zero cell saturation. The HIGHEST\\_SATURATED option has an additional complication for certain types of grids specified using the DISU Package. When the DISU Package is used, a cell may have more than one cell underlying it. If the overlying cell were to become inactive, there is no straightforward method for determining how to apportion the mass source loading rate to the underlying cells. In this case, the approach described by \\cite{modflowusg} is used. The mass source loading rate is assigned to the first active cell encountered (determined by searching through the underlying cell numbers from the lowest number to the highest number). In this manner, the total mass source loading rate is conserved; however, the spatial distribution of the applied mass source loading rate may not be maintained as layers become dry or wet during a simulation."
+
+[[items]]
+section = "features"
+subsection = "basic"
+description = "Added a coordinate reference system option CRS to discretization packages. For example, an EPSG integer code, authority string, or Open Geospatial Consortium Well-Known Text (WKT) specification. This option does not affect simulation results, but is written to the binary grid file so that postprocessors can locate the grid in space. A new binary grid file version number (2) is introduced to indicate that CRS information may be present."

doc/ReleaseNotes/mk_releasenotes.py

@@ -15,9 +15,11 @@
     parser = argparse.ArgumentParser()
     parser.add_argument("--toml", default="develop.toml")
     parser.add_argument("--tex", default="develop.tex")
+    parser.add_argument("--patch", default=False, action="store_true")
     args = parser.parse_args()
     toml_path = Path(args.toml).expanduser().absolute()
     tex_path = Path(args.tex).expanduser().absolute()
+    patch = args.patch
     if not toml_path.is_file():
         warn(f"Release notes TOML file not found: {toml_path}")
         sys.exit(0)
@@ -45,9 +47,13 @@
     with open(tex_path, "w") as tex_file:
         with open(toml_path, "rb") as toml_file:
             content = tomli.load(toml_file)
-            sections = content.get("sections", [])
-            subsections = content.get("subsections", [])
+            sections = content.get("sections", {})
+            subsections = content.get("subsections", {})
             items = content.get("items", [])
+            # if patch, only include fixes
+            if patch:
+                sections = {k: v for k, v in sections.items() if k == "fixes"}
+                items = [item for item in items if item.get("section") == "fixes"]
             # make sure each item has a subsection entry even if empty
             for item in items:
                 if not item.get("subsection"):