List of deprecations

[schlunma]

We currently do not have a list where we list all of our deprecations. In order to keep track of the version the deprecated features are scheduled for removal, it would be great to have such a list.

What would be a good place for this? Our documentation? Something on GitHub? @ESMValGroup/esmvaltool-coreteam

[valeriupredoi]

I reckon in the documentation it would fit very well, look at the Pytest deprecations and removals page

[zklaus]

It would indeed be good to have an overview. However, manual collection of the deprecations doesn't sound appealing because it is some overhead, creates duplication, and is likely to lead to inconsistencies at some point.
Can we collect that information automatically? Perhaps finding the DeprecationWarnings?

[schlunma]

An automatic collection sounds like a great idea!

Maybe we could unify our documentation of deprecated features in this context? For example, using the sphinx directive .. deprecated:: 2.5.0 or decorator @deprecated(reason=..., version=...)? This would make it very easy to automatically retrieve the deprecations and the corresponding versions.

[valeriupredoi]

excellent idea @schlunma - my next favourite thing to coding is no coding at all 😆

[sloosvel]

After today's release planning meeting, I created the v2.8.0 milestone to assign this issue so that it does not get forgotten.

But the idea is that, in case there are any deprecated features occurring in v2.7.0, they should already be listed following the approach that @schlunma proposed.

[schlunma]

Example for deprecated feature:

ESMValCore/esmvalcore/iris_helpers.py

Lines 109 to 138 in ed81a3c

	def var_name_constraint(var_name):
	""":class:`iris.Constraint` using ``var_name``.
	Warning
	-------
	.. deprecated:: 2.6.0
	This function has been deprecated in ESMValCore version 2.6.0 and is
	scheduled for removal in version 2.8.0. Please use the function
	:class:`iris.NameConstraint` with the argument ``var_name`` instead:
	this is an exact replacement.
	Parameters
	----------
	var_name: str
	``var_name`` used for the constraint.
	Returns
	-------
	iris.Constraint
	Constraint.
	"""
	deprecation_msg = (
	"The function ``var_name_constraint`` has been deprecated in "
	"ESMValCore version 2.6.0 and is scheduled for removal in version "
	"2.8.0. Please use the function ``iris.NameConstraint`` with the "
	"argument ``var_name`` instead: this is an exact replacement."
	)
	warnings.warn(deprecation_msg, ESMValCoreDeprecationWarning)
	return NameConstraint(var_name=var_name)