Use "TODO" comments to track deprecated codes or workarounds for old versions

[seisman]

Sometimes, we may need to mark part of the codes for future reference. For example,

1. Deprecated parameters/syntax/functions/methods should be removed in the future. E.g.,

   pygmt/pygmt/clib/session.py

   Lines 1940 to 1944 in 5702209

   	msg = (
   	"API function 'Session.virtualfile_from_data()' has been deprecated since "
   	"v0.13.0 and will be removed in v0.15.0. Use 'Session.virtualfile_in()' "
   	"instead."
   	)

2. Workarounds for old package versions should be removed after we drop the support of old versions. E.g.,
   

   pygmt/pygmt/clib/conversion.py

   Lines 180 to 187 in 5702209

   	# Workarounds for pandas < 2.2. Following SPEC 0, pandas 2.1 should be dropped in
   	# 2025 Q3, so it's likely we can remove the workaround in PyGMT v0.17.0.
   	if (
   	Version(pd.__version__) < Version("2.2") # pandas < 2.2 only.
   	and hasattr(data, "dtype") # NumPy array or pandas objects only.
   	and hasattr(data.dtype, "numpy_dtype") # pandas dtypes only.
   	and data.dtype.kind in "iuf" # Numeric dtypes only.
   	): # pandas Series/Index with pandas nullable numeric dtypes.

   
   

   pygmt/pygmt/src/timestamp.py

   Line 102 in 5702209

   if Version(__gmt_version__) < Version("6.5.0"):

   
   

   pygmt/pygmt/conftest.py

   Lines 8 to 9 in 5702209

   	# Keep this until we require numpy to be >=2.0
   	# Address https://github.com/GenericMappingTools/pygmt/issues/2628.

3. More other cases.

Currently, for case 1, we use the grep --include="*.py" -r vX.Y.Z command to find the matches, but for case 2, we don't have a way to track them.

To better track codes that should be removed/refactored in the future, I suggest using the TODO comments in our source codes. It should be noted that TODO comments should not be abused for marking unimplemented features or incomplete documentation, which should be tracked by issues instead.

There is no style guide like PEP8 for TODO comments. Looking at this todo tool (https://github.com/ianlewis/todos), the ruff's TODO linter, and also searching for the web, here are the TODO comment styles I've found:

# TODO: Description 
# TODO(somebody): Description
# TODO@somebody: Description
# TODO(#1234567): Description

Since we're using TODO comments for tracking deprecated codes/workarounds, I think we can use the following style:

# TODO(Package>=vX.Y.Z): Description

e.g.,

# TODO(GMT>=6.5.0): Remove the workaround below.
# TOOD(pandas>=2.0): Remove the workaround for pandas<2.0.
# TODO(PyGMT>=0.16.0): Remove the deprecated parameter/function/method ...

Then we can use grep "# TODO" **/* to find all TODOs. Some editors even have plugins to highlight TODO comments or show all TODOs in a compact way.

If agreed, we should do:

• Find all TODOs in our codebase and refactor them into TODO comments Use TODO comments to track deprecations and workarounds #3722
• Enable some rules in ruff's TD linter Enable ruff's flake8-todos (TD) rules #3723
• Mention TODO comments in the contributing guides Add TODO comments in the maintainers guides and update the release checklist #3724
• Update our release checklist Add TODO comments in the maintainers guides and update the release checklist #3724