docs: add deprecation policy to dev docs and release guide

[wpbonelli]

Add deprecation guidelines after discussion with @langevin-usgs, @jdhughes-usgs, @mjreno. Followup to #1878.

• describe policy loosely following NEP 23 in
  • DEVELOPER.md
  • docs/make_release.md
• update table of contents in DEVELOPER.md
• fix some autotest names

PRs applying deprecations introduced in version 3.3.5 or before:

• refactor(vtk): remove deprecated export_* functions #1890
• refactor(plotutil): remove deprecated utilities #1891
• refactor(shapefile_utils): remove deprecated SpatialReference usages #1892
• refactor(modflow): remove deprecated UZF option, disallow USG #1893
• refactor(mf6): remove deprecated features #1894

[codecov]

Codecov Report

Merging #1889 (6094575) into develop (70b9a37) will not change coverage.
The diff coverage is n/a.

@@           Coverage Diff           @@
##           develop   #1889   +/-   ##
=======================================
  Coverage     72.2%   72.2%           
=======================================
  Files          257     257           
  Lines        56488   56488           
=======================================
  Hits         40836   40836           
  Misses       15652   15652           

[mwtoews]

Thanks, I'm aware of NEP 23 and think it is a good inspiration for a deprecation policy.

Would some recent deprecations (e.g. here) be modified that they are anticipated to be changed for FloPy 3.7?

[wpbonelli]

Thanks @mwtoews would you suggest correcting anticipated removal version numbers, or removing/omitting them? Looks like numpy does not include them in their sample warning messages, I guess they are inherently a bit speculative.

[mwtoews]

Thanks, I see that only the version the feature was deprecated should be specified, but the exact removal version does not need to be specified. It is also not possible to accurately "guess" if the +2 versions from now would be (e.g.) 3.6.0 or 4.0.0.

Lets leave the existing deprecation messages alone for now, but going forward only specify the version they were deprecated.