pygmt.grdclip: Deprecate parameter 'new' to 'replace' (remove in v0.19.0)

[seisman]

Addressing #3882 (comment).

Hopefully it can be approved and merged into v0.15.0

[yvonnefroehlich]

Should we add tests for this parameter and the usage of the old parmeter name?

Similar to the mode parameter of grdfill:

pygmt/pygmt/tests/test_grdfill.py

Lines 143 to 150 in a11fc15

	# TODO(PyGMT>=0.19.0): Remove this test.
	def test_grdfill_deprecated_mode(grid, expected_grid):
	"""
	Test that grdfill fails with deprecated `mode` argument.
	"""
	with pytest.warns(FutureWarning):
	result = grdfill(grid=grid, mode="c20")
	xr.testing.assert_allclose(a=result, b=expected_grid)

Currently, it looks like only above, below and between are included in the tests (https://github.com/GenericMappingTools/pygmt/blob/main/pygmt/tests/test_grdclip.py).

[seisman]

Should we add tests for this parameter and the usage of the old parmeter name?

Similar to the mode parameter of grdfill:

pygmt/pygmt/tests/test_grdfill.py

Lines 143 to 150 in a11fc15

	# TODO(PyGMT>=0.19.0): Remove this test.
	def test_grdfill_deprecated_mode(grid, expected_grid):
	"""
	Test that grdfill fails with deprecated `mode` argument.
	"""
	with pytest.warns(FutureWarning):
	result = grdfill(grid=grid, mode="c20")
	xr.testing.assert_allclose(a=result, b=expected_grid)

Currently, it looks like only above, below and between are included in the tests (https://github.com/GenericMappingTools/pygmt/blob/main/pygmt/tests/test_grdclip.py).

Thanks. Added.

[weiji14]

Clarify that only the test below is to be removed, not the entire unit test.

Suggested change

	# TODO(PyGMT>=0.19.0): Remove this test for the 'new' parameter
	# TODO(PyGMT>=0.19.0): Remove this test below for the 'new' parameter