Skip to content

development planning - #537

Draft
wpbonelli wants to merge 77 commits into
modflowpy:developfrom
wpbonelli:dev-plans
Draft

wpbonelli wants to merge 77 commits into
modflowpy:developfrom
wpbonelli:dev-plans

Conversation

@wpbonelli

@wpbonelli wpbonelli commented Nov 3, 2026 •

Copy link
Copy Markdown
Member

too much robot

but the essence is there

  • add detailed plans on specific topics
  • add general strategy/sequencing to get to 4.x

wpbonelli and others added 13 commits November 3, 2026 11:08
Co-Authored-By: Claude Opus 5.5 <[email protected]>
Fill in the representation spec's outline (grid dims and coordinates,
tree and type tags, period data, time, attributes and fill values) from
the plans where each piece was designed, and move the MF6 NetCDF format
notes into it. The package plan keeps direction and all open questions;
the export plan keeps the implementation steps. Check in the plans the
docs still depend on, and drop references to local-only files.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
The MMP plan sequences what's left before MMP into parallel tracks
with a gate, and records the release shape: alphas and betas from this
repo via GitHub, release candidates from flopy's 4.x branch, GA as the
last candidate. map.md gains the release-candidate stage. The
integration plan is refreshed against develop 8d25e4b and flopy
aca52382, and its phases and checkpoints follow the same release shape.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
layout-logical-decisions.md states one rule from the modflowpy#287 work (the
object model holds input as given, logical forms are views, dynamic
derivations are never materialised silently) and applies it to the
open MMP issues it bears on: modflowpy#229, modflowpy#523, modflowpy#345, modflowpy#226 and modflowpy#259, with the
MF6 source checked for the UZF and SFR claims. It also proposes an
Options section for the representation spec and separates round-trip
from cross-engine equivalence.

mmp-plan.md links it from Tracks B and C, notes that modflowpy#226, modflowpy#259 and
binding-graph navigation share one attach operation, and adds the rule
to the decisions table.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
The research behind layout-logical-decisions.md: the modflowpy#287 directions
and comment draft, the relational spec draft, the polymorphism notes,
the option classification and constraint audit plans and results, and
the scripts and data they came from (option-classification/,
constraint-audit/).

Co-Authored-By: Claude Opus 5.5 <[email protected]>
The integration plan now defers Phase 0's flopy3 work to the migration
plan (aliases in flopy4, compat names in 4.x), uses the MMP plan's track
letters, and points tier E's normalizer at the option labels. The export
plan's phase 1 picks up the layout/logical rule for options and
constants. Stale code references in the migration plan are fixed.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Deprecated flopy3 forms warn with FutureWarning, in flopy4 and the 4.x
compat layer. The modflowpy#287 comment draft and polymorphism notes follow the
directions doc's separate-classes revision. Adds reference-fields-notes
and user-dir-classes-plan, which other plans link to; the finished
reference-fields plan is archived instead. Notes the two meanings of
"layout" in the representation spec, and restamps docs still accurate
at develop 8d25e4b.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
…aders

- docs/dev/plans.md indexes every plan by topic with status; plans are
  grouped under integration/, xarray/, components/ and spec/, and
  excluded from the docs build
- spec/overview.md (from the modflowpy#287 directions doc) defines the terms and
  states the hypotheses and plan; the option classification and
  constraint audit plan/results pairs are merged, findings first
- spec/dfn-gaps.md collects the DFN and memory catalog gaps for MF6 and
  devtools developers
- reference-fields.md rewritten to match the current code
- status lines and relative links throughout; drop session-only framing
- untrack the GitHub post drafts; exclude the research scripts from ruff

Co-Authored-By: Claude Opus 5.5 <[email protected]>
@wpbonelli wpbonelli added documentation Improvements or additions to documentation meta Planning, strategy, developer tooling, etc labels Nov 3, 2026
- Source-only plans move to docs/dev/plans/ (index at plans/README.md);
  one exclude pattern replaces six.
- spec/ -> dfn-spec/, to avoid confusion with flopy4.spec and the SRS.
- flopy-integration.md -> replacing-flopy-mf6.md, flopy3-migration.md ->
  aliases-and-codemod.md, named for what each covers.
- TOC: drop protocols-plan and array-converter-design (deleted in modflowpy#322),
  add load-benchmarks (was orphaned).
- codespell: skip the research data folder (regex word stems, quoted MF6
  messages), as ruff already does.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
@wpbonelli
wpbonelli marked this pull request as ready for review November 3, 2026 21:27
@wpbonelli
wpbonelli marked this pull request as draft November 3, 2026 21:31
wpbonelli and others added 12 commits November 4, 2026 04:21
Live plans from the repo root, a worktree and fork branches go under
docs/dev/plans by topic (components, lists, loading, cleanup, integration,
dfn-spec), listed in the index. Finished and superseded plans go in
docs/dev/plans/archive as last written, with their own index; codespell
skips the archive. Mentions of the old file names are now links.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Plans with nothing left to do move to the archive. The two follow-up
lists become maintenance/backlog.md with the three items still open.
cleanup/ is now maintenance/ and loading/ is now io/. xarray/package.md
is now xarray/overview.md, and lists/design.md, the modflowpy#287 directions note
and integration/python-codes.md get descriptive names.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Drop status banners and decision tracking, describe the design as it
stands, and move the sel_z layer-label bug to the backlog.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Rewrite list-fields.md against develop and move the row layout into it;
record-unify.md keeps only the Item/Record merge.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Rewrite mixin-fields.md for the sync-time scan alone, condense the
converter-simplification report, and archive typed-loader-wiring.md,
which the simplify-converter branch supersedes.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Archive the dead-code audit, now done, moving its open item to the
backlog, and update dev-docs.md for the rewritten reference notes.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Merge modflowapi.md and xmi-api.md into one short modflowapi.md, and cut
python-models.md to the idea; the full drafts are on dev-plans-full.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Drop status framing from the research reports, archive
polymorphism-hypotheses.md (overview.md supersedes it), and drop the
Status columns and legend from the plans index.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
wpbonelli and others added 30 commits November 5, 2026 09:37
A connector for flopy4, and perhaps MF6, with what it needs that the slice
lacks and a round trip as the first test. Not part of this plan.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
The simplification plan leaves the simplify-converter branch, so this copy
becomes the only one. Keep its trimmed form, and take the rebase's results:
one loader on the branch, current sizes, what develop fixed, and the
single-component loader and sync-time names as what's next.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
period_data, WorkspaceComponent, kper and <name>_kper in the live plans,
keeping the old names only where they're flopy3's or a record of a decision.
A period list's sparse dim stays entry, with the reasons in representation.md,
and the name for other lists' dims is open. The audit's renames are done.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Not started. get_data, set_data, .array and .data on PeriodRows, if unchanged
3.x scripts become a goal, since modflowpy#541 only covers the names.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
The basic loader's stricter errors, what _check_typed_grammar catches, and the
error table rerun for the basic loader.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Record D5's reversal in the audit, and use the name throughout the plans.
With the field and flopy3's name the same on most stress packages, the
period-list values plan loses its argument for a legacy-only subclass.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
factoring.md says where a constraint or format fact belongs: the DFN, the
classes, the codec or a named check. It also says when the DFN should stop
growing, and lists three structural changes that remove constraints. The
converter plan records that modflowpy#544 no longer reads stored DFNs at runtime.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
…ammars

binding-navigation.md plans step 4: the flopy4 side of binding
parameters, keys.py on one resolver, and RCHA <-> RCH.
bindings-as-attribute-grammar.md relates the spec's bindings to
attribute grammars, with what that predicts for flopy4. ddl-next-steps
records step 3 done on devtools' binding-params, and the twri rerun.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Adds what binding means in programming languages, where the spec's term
matches and differs, and Verilog module instantiation as a closer analogue,
with a Verilog column in the vocabulary table. Updates binding-row wording
to siblings, and the flow_model row, to match the spec.

Co-Authored-By: Claude Opus 5.5 <[email protected]>

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Improvements or additions to documentation meta Planning, strategy, developer tooling, etc

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant