From 6094575a6b489cf8e38c7a8268afd4ef4098f734 Mon Sep 17 00:00:00 2001 From: Wes Bonelli Date: Tue, 1 Aug 2023 14:37:55 -0400 Subject: [PATCH] docs: add deprecation policy to dev docs and release guide * describe deprecation policy loosely following NEP 23 * fix some autotest names per pending deprecations --- DEVELOPER.md | 21 ++++++++++++++++++--- autotest/test_export.py | 4 ++-- docs/make_release.md | 8 ++++++-- 3 files changed, 26 insertions(+), 7 deletions(-) diff --git a/DEVELOPER.md b/DEVELOPER.md index 6230132c9a..ad1d04c76b 100644 --- a/DEVELOPER.md +++ b/DEVELOPER.md @@ -17,11 +17,11 @@ This document describes how to set up a FloPy development environment, run the e - [Manually installing executables](#manually-installing-executables) - [Linux](#linux) - [Mac](#mac) + - [Updating FloPy packages](#updating-flopy-packages) - [Examples](#examples) - [Scripts](#scripts) - [Notebooks](#notebooks) - - [Developing example Notebooks](#developing-example-notebooks) - - [Adding a new notebook to the documentation](#adding-a-new-notebook-to-the-documentation) + - [Developing new notebooks](#developing-new-notebooks) - [Adding a tutorial notebook](#adding-a-tutorial-notebook) - [Adding an example notebook](#adding-an-example-notebook) - [Tests](#tests) @@ -33,6 +33,10 @@ This document describes how to set up a FloPy development environment, run the e - [Performance testing](#performance-testing) - [Benchmarking](#benchmarking) - [Profiling](#profiling) +- [Branching model](#branching-model) +- [Deprecation policy](#deprecation-policy) +- [Miscellaneous](#miscellaneous) + - [Locating the root](#locating-the-root) @@ -358,6 +362,17 @@ By default, `pytest-benchmark` will only print profiling results to `stdout`. If This project follows the [git flow](https://nvie.com/posts/a-successful-git-branching-model/): development occurs on the `develop` branch, while `main` is reserved for the state of the latest release. Development PRs are typically squashed to `develop`, to avoid merge commits. At release time, release branches are merged to `main`, and then `main` is merged back into `develop`. +## Deprecation policy + +This project loosely follows [NEP 23](https://numpy.org/neps/nep-0023-backwards-compatibility.html). Basic deprecation policy includes: + +- Deprecated features should be removed after at least 1 year or 2 non-patch releases. +- `DeprecationWarning` should be used for features scheduled for removal. +- `FutureWarning` should be used for features whose behavior will change in backwards-incompatible ways. +- Deprecation warning messages should include the deprecation version number (the release in which the deprecation message first appears) to permit timely follow-through later. + +See the linked article for more detail. + ## Miscellaneous ### Locating the root @@ -370,4 +385,4 @@ For a script in a subdirectory of the root, for instance, the conventional appro ```Python project_root_path = Path(__file__).parent.parent -``` +``` \ No newline at end of file diff --git a/autotest/test_export.py b/autotest/test_export.py index 9f4eac4d32..379353be18 100644 --- a/autotest/test_export.py +++ b/autotest/test_export.py @@ -1112,7 +1112,7 @@ def test_vtk_transient_array_2d(function_tmpdir, example_data_path): @requires_pkg("vtk") @pytest.mark.slow -def test_vtk_export_packages(function_tmpdir, example_data_path): +def test_vtk_add_packages(function_tmpdir, example_data_path): # test mf 2005 freyberg ws = function_tmpdir mpath = example_data_path / "freyberg_multilayer_transient" @@ -1572,7 +1572,7 @@ def load_iverts(fname, closed=False): @pytest.mark.mf6 @requires_pkg("vtk") -def test_vtk_export_model_without_packages_names(function_tmpdir): +def test_vtk_add_model_without_packages_names(function_tmpdir): from vtkmodules.util.numpy_support import vtk_to_numpy from vtkmodules.vtkIOLegacy import vtkUnstructuredGridReader diff --git a/docs/make_release.md b/docs/make_release.md index c8bcab8889..1825b3d7a3 100644 --- a/docs/make_release.md +++ b/docs/make_release.md @@ -28,11 +28,15 @@ The FloPy release procedure is mostly automated with GitHub Actions in [`release 3. Update the authors in `CITATION.cff` for the Software/Code citation for FloPy, if required. -4. Review deprecations. To search for deprecation warnings with git: `git grep [-[A/B/C]N] ` for N optional extra lines of context. Some terms to search for: +4. If this is a minor or major release, review deprecation warnings (if this is a patch release, skip this step). Correct any deprecation version numbers if necessary — for instance, if the warning was added in the latest development cycle but incorrectly anticipated the forthcoming release number (e.g., if this release was expected to be minor but was promoted to major). If any deprecations are due this release, remove the corresponding features. FloPy loosely follows [NEP 23](https://numpy.org/neps/nep-0023-backwards-compatibility.html) deprecation guidelines: removal is recommended after at least 1 year or 2 non-patch releases. - - deprecated:: + To search for deprecation warnings with git: `git grep [-[A/B/C]N] `, where N is the optional number of extra lines of context and A/B/C selects post-context/pre-context/both, respectively. Some terms to search for: + + - deprecated + - .. deprecated:: - DEPRECATED - DeprecationWarning + - FutureWarning ## Release procedure