[DEV WORKFLOW]: Deprecation removal claims are not enforced in pvlib's lifecycle

[echedey-ls]

Is your feature request related to a problem? Please describe.
Frustration kicks in when I find deprecated features that were supposed to be removed in the past. It's like, am I browsing someone's branch not up-to-date? Do I have some virtual environment with a pvlib fossil installed? The answer is, no, it's just some legacy deprecated code still there!

Jokes aside, here are some examples found on the wild of issues reporting forgotten removals:

• [DEPRECATION]: pvlib.iotools.read_tmy3 deprecated recolumn parameter removal scheduled for v0.11.0, still there #2324
• Deprecated pvsystem.sapm_spectral_loss not removed #2243 (TBF this one didn't claim any removal version, just stated soon after its announcement in v0.10.0)
• Deprecated pvlib.atmosphere.first_solar_spectral_correction not scheduled for removal #2130 (same as previous)

Describe the solution you'd like
Any procedure that avoids forgetting them. The best one that comes to my mind right now is:

1. Create issues immediately after a PR introduces a deprecation, label and milestone them appropriately:
   1. Requires creating more version milestones.
   2. I'd love labels for them, at least deprecation. May consider others as well.
2. Require @fail_on_pvlib_version in warning tests in the PRs introducing the deprecation, so tests fail when pvlib gets to the scheduled removal version.
3. Add or modify PR template to remind contributors and maintainers.

Describe alternatives you've considered
a. Add a label introduces deprecation to easily browse which PRs may need a follow-up.
b. Keep the original issue of the PR introducing deprecations open, and reassign milestone. (-1)
c. Rely on the quality testers (i.e., users (i.e., do nothing)) (-1)

Additional context
I fear the same outcome for:

• Change g_poa_effective to effective_irradiance #2235
• Adopt dni_clear variable name for clearsky DNI #2274
• Adopt ghi_clear variable name for clearsky GHI #2306.

Feel free to weight in, specially if you know of other alternatives :D

[kandersolar]

SciPy has a pinned "deprecation tracker" issue. I've never opened it up to look at it, but perhaps looking at their process would be instructive for us.

[AdamRJensen]

Potentially we could create an issue that acts as a deprecation tracker for each upcoming major version? A bit like the release planning issues, but created much earlier

[echedey-ls]

I propose opening and pinning the template down below. Feel free to propose any changes. I've added the 0.11.0 as an example of how it would look like. I also recommend limiting conversation only to collaborators / maintainers, since this issue is expected to have a long lifecycle and a lot of conversation may pile up.

Deprecations Tracking Issue

This issue is used to track past, present, and future deprecations and make the required follow-ups. Maintainers may update this issue whenever a feature is deprecated, renamed, or removed.

If you have found a deprecated feature that is not here, please report it via a new issue or the mailing list.

Upcoming changes

• Not scheduled

  • Removal of dictionary alias pvlib.irradiance.SURFACE_ALBEDOS.
    • Use pvlib.albedo.SURFACE_ALBEDOS instead.
    • Deprecated in v0.11.0
    • Move albedo dictionary from pvlib.irradiance to pvlib.albedo #2095

• v0.12.0

  • Removal of parameter recolumn of pvlib.iotools.read_tmy3()
    • Deprecated in v0.10.0
    • [DEPRECATION]: pvlib.iotools.read_tmy3 deprecated recolumn parameter removal scheduled for v0.11.0, still there #2324
  • Removal of function pvsystem.sapm_spectral_loss()
    • Deprecated in v0.10.0
    • Deprecated pvsystem.sapm_spectral_loss not removed #2243
  • Removal of function alias pvlib.atmosphere.first_solar_spectral_correction().
    • Use pvlib.spectrum.spectral_factor_firstsolar() instead.
    • Deprecated in v0.10.0
    • Deprecated pvlib.atmosphere.first_solar_spectral_correction not scheduled for removal #2130
  • Removal of function pvlib.spectrum.get_am15g()
    • Use pvlib.spectrum.get_reference_spectra(standard="ASTM G173-03")["global"] instead
    • Deprecated in v0.11.0

• v0.13.0

  • Renamed parameter names dni_clearsky and clearsky_dni in favour of dni_clear
    • Affects pvlib.irradiance.dirindex() and pvlib.irradiance.dni()
    • Deprecated in v0.11.2
    • Standardise variable name for clearsky GHI and DNI, add to glossary #2272
  • Renamed parameter name ghi_clearsky to ghi_clear
    • Affects pvlib.irradiance.dirindex() and pvlib.irradiance.clearsky_index()
    • Deprecated in v0.11.2
    • Standardise variable name for clearsky GHI and DNI, add to glossary #2272

Past changes

• v0.11.0

  • Removal of function pvlib.modelchain.basic_chain()
    • Remove deprecated basic_chain method #1862
  • Removal of function pvlib.irradiance.poa_horizontal_ratio()
    • pvlib.irradiance.poa_horizontal_ratio should be removed #1697
  • Replacement of function pvlib.iotools.read_srml_month_from_solardat() by pvlib.iotools.get_srml()
    • Deprecated in v0.10.0
    • Add get_srml iotools function; deprecate read_srml_month_from_solardat  #1779
  • Removal of parameter ivcurve_pnts of pvlib.pvsystem.singlediode()

[wholmgren]

I am +1 for a deprecation tracker issue. I think that's complementary to the automated deprecation tracker tests. If we want to keep the automated deprecation tests working (I do), then we need to ensure that we always create prereleases for versions with deprecations (currently 0.x). There is a wiki on release procedures that could probably use some updating: https://github.com/pvlib/pvlib-python/wiki/Release-procedures#pre-releases

[echedey-ls]

I will open the proposed issue in the short term if no objections are made. I consider appropriate that the conversation is limited to collaborators. I cannot change that with my current permissions, so I will need somebody from @pvlib/pvlib-maintainer to do so.

[echedey-ls]

Feel free to limit conversation of #2396, and possibly pin it too.