refactor(distribution): automate release procedure

[wpbonelli]

This PR refactors distribution/ scripts, documents release-related procedures in distribution/README.md, and automates the release process.

Distribution scripts

Scripts are updated to use pathlib. Each is given an argparse CLI. Shared utilities are moved to distribution/utils.py. Tests for the scripts are updated to use pytest tempdir fixtures. More test cases are added. Some tests modify files in the repo and clean up after with git restore, so the tests in distribution/ shouldn't be run in parallel. Care should also be taken before running the tests locally, as they will restore files in doc/, make/, and utils/. Other changes include:

• locate relative paths by script location (__file__) instead of current working directory
  • makes scripts runnable from anywhere (previously had to run from distribution/)
• import meson_build() from modflow-devtools
• refactor scripts
  • rename evaluate_run_times.py -> benchmark.py
  • rename make_release.py -> update_version.py
  • rename mkdist.py -> build_dist.py
  • introduce build_docs.py
    • files to build can be specified on the command line
    • can be used for nightly build or official release using different args
    • de-duplicates/deprecates functionality in autotest/build_mfio_tex.py
  • remove build_nightly.py
    • dev/nightly builds can be created with build_dist.py --development

This changeset allows the MODFLOW-USGS/modflow6-nightly-build repo to use distribution/build_dist.py, making it unnecessary to have a separate make_distribution.py script and requirements.txt in that repo

Release automation

A new CI workflow release.yml is added to automate the release procedure. The workflow is triggered when a release candidate branch is pushed to the MODFLOW-USGS/modflow6 repository. The branch name must follow semantic versioning conventions, with or without an rc suffix to indicate whether the branch is approved for release (for instance, v6.4.0rc). The workflow first builds modflow6 binaries, then downloads examples, benchmarks and documentation via the GitHub API (only building them if needed), then finally zipping everything up for distribution. It is largely identical to the procedure previously outlined at the top of mkdist.py, except that

• scripts check to see if their targets exist before re-creating them
• example models are downloaded from the modflow6-examples repository if available
• benchmarks and some documentation artifacts are downloaded from workflow runs in this repo (built by docs.yml) if available

More extensive docs for the procedure are added to distribution/README.md.

Triggering a release

Under this scheme, a new release candidate build can be triggered by creating a branch named v<semver>rc from the top of develop and pushing it to this repository.

If the branch name ends with rc, it is considered a release candidate and the workflow is a dry run, building, testing and creating artifacts with development mode binaries then stopping short of a release. If the candidate build passes, it can be promoted by removing rc from the branch name and pushing the new branch — this will trigger the release workflow in production mode, rebuilding with develop mode off. If/when the build succeeds, a draft PR is autocreated against the master branch. The release can be approved by merging PR into master, which triggers a final job to create a tagged draft release, upload distributions and release notes to it as assets, and autocreate another PR to reinitialize develop by updating from master, reset version files, and set IDEVELOPMODE back to 1. The release can be finalized by reviewing the draft release post, substituting in citations and any other additional content, and publishing.

Miscellaneous

• bump docs.yml CI jobs to ubuntu-22.04 for compatibility with GCC 12
• move .fprettify.yaml to project root (not solely distribution-related)
• update src/Utilities/comarg.f90 to de-duplicate version string output from mf6 -v (and add test)
• add path CLI arg to doc/ReleaseNotes/mk_runtimecomp.py to specify dist locn
• add pytest-cases and pytest-dotenv to environment.yml
• merge CI jobs for testing makefiles/dist scripts into shared CI test job
• don't run ci.yml on changes to markdown files or docs

[langevin-usgs]

Few minor things that might need to be adjusted, based on recent changes to develop.

[langevin-usgs]

This was updated to 6.4.1 on develop. I think we also need to do that here.

[wpbonelli]

Tentative solution discussed via DM and reproduced below for posterity:

The release workflow automatically sets version files to the version specified in the name of the branch triggering the workflow. IDEVELOPMODE is also set to 0. These changes are included in the PR opened against master from the release branch. After the release is approved and changes are merged to master, another PR is opened against develop to update from master, reset IDEVELOPMODE to 1, and increment the minor version number in preparation for the next minor version release.

Patch releases are generally expected to branch from master, since develop may contain broader-scoped changes. Minor version releases are generally expected to branch from develop.