docs: Versioning policy

[dangotbanned]

Will close: #3454

Based on discussions in #3454 (comment) and #3454 (comment)

Public API definition is was blocking, see discussion in #3478 (reply in thread).

Tasks

• Background on what versioning has been used so far
• Define the Public API
• Define deprecation process
  • Period(s)
    • Deprecation/breaking changes policy & process #3454 (comment)
    • Mostly when can changes be introduced, how long can users expect deprecated support
  • Warnings
    • feat(typing): @deprecated versioning, IDE highlighting #3455
    • https://docs.pola.rs/development/versioning/#deprecation-warnings

[dangotbanned]

Special handling of upstream vega-lite schema changes

I've moved this from the main task list, since I'm not sure of a good solution but maybe someone else has an idea.

• Should altair support (w/ deprecation) input that is no longer compliant with the vega-lite schema?
• See alt.param as of v5.0.0

altair/altair/vegalite/v5/api.py

Lines 448 to 482 in 7f05ecb

	parameter = Parameter(name)
	if empty is not Undefined:
	parameter.empty = empty
	if parameter.empty == "none":
	warnings.warn(
	"""The value of 'empty' should be True or False.""",
	utils.AltairDeprecationWarning,
	stacklevel=1,
	)
	parameter.empty = False
	elif parameter.empty == "all":
	warnings.warn(
	"""The value of 'empty' should be True or False.""",
	utils.AltairDeprecationWarning,
	stacklevel=1,
	)
	parameter.empty = True
	elif (parameter.empty is False) or (parameter.empty is True):
	pass
	else:
	msg = "The value of 'empty' should be True or False."
	raise ValueError(msg)
	if "init" in kwds:
	warnings.warn(
	"""Use 'value' instead of 'init'.""",
	utils.AltairDeprecationWarning,
	stacklevel=1,
	)
	if value is Undefined:
	kwds["value"] = kwds.pop("init")
	else:
	# If both 'value' and 'init' are set, we ignore 'init'.
	kwds.pop("init")

Issues

The example I've given highlights the conflict between how SemVer specifies deprecation and the most recent major version of altair.

v5.0.0 should be where a breaking change is made, but was instead a backwards-compatible change.

This is complicated by (AFAIK) the change occuring - without deprecation - in vega-lite.

[dangotbanned]

@mattijn Do you think there is a need to state here about the level of docs for deprecated functionality?
E.g. removal from API Reference, reduced docstrings

• docs: Undoc deprecated functionality #3509

[mattijn]

I trust you here👍

[binste]

Special handling of upstream vega-lite schema changes

I've moved this from the main task list, since I'm not sure of a good solution but maybe someone else has an idea.

• Should altair support (w/ deprecation) input that is no longer compliant with the vega-lite schema?
• See alt.param as of v5.0.0

altair/altair/vegalite/v5/api.py

Lines 448 to 482 in 7f05ecb

	parameter = Parameter(name)
	if empty is not Undefined:
	parameter.empty = empty
	if parameter.empty == "none":
	warnings.warn(
	"""The value of 'empty' should be True or False.""",
	utils.AltairDeprecationWarning,
	stacklevel=1,
	)
	parameter.empty = False
	elif parameter.empty == "all":
	warnings.warn(
	"""The value of 'empty' should be True or False.""",
	utils.AltairDeprecationWarning,
	stacklevel=1,
	)
	parameter.empty = True
	elif (parameter.empty is False) or (parameter.empty is True):
	pass
	else:
	msg = "The value of 'empty' should be True or False."
	raise ValueError(msg)
	if "init" in kwds:
	warnings.warn(
	"""Use 'value' instead of 'init'.""",
	utils.AltairDeprecationWarning,
	stacklevel=1,
	)
	if value is Undefined:
	kwds["value"] = kwds.pop("init")
	else:
	# If both 'value' and 'init' are set, we ignore 'init'.
	kwds.pop("init")

Issues

The example I've given highlights the conflict between how SemVer specifies deprecation and the most recent major version of altair.

v5.0.0 should be where a breaking change is made, but was instead a backwards-compatible change.

This is complicated by (AFAIK) the change occuring - without deprecation - in vega-lite.

First thought is that if something is no longer compliant with the VL schema and it leads to a breaking change, we have to support it until the next major version following the policy you're drafting. If it's a feature which we know was heavily used by users and we can write some compatibility code around it, we can optionally consider deprecating it and still supporting it for a while. If we can make the lives of our users easier, I'm all for it :) What do you think?

[dangotbanned]

First thought is that if something is no longer compliant with the VL schema and it leads to a breaking change, we have to support it until the next major version following the policy you're drafting. If it's a feature which we know was heavily used by users and we can write some compatibility code around it, we can optionally consider deprecating it and still supporting it for a while. If we can make the lives of our users easier, I'm all for it :) What do you think?

Thanks @binste, reading your comment and then re-reading the policy I've drafted has made me think I've overcomplicated this.
Will adapt that into the next draft

[dangotbanned]

Ready for review @binste @mattijn

Feeling confident all the ideas that came up are now documented.

However, I'm not a writer, so please feel free to directly edit to taste

[joelostblom]

This looks good for me, thanks for putting it together.

[dangotbanned]

Thanks both @joelostblom @mattijn

[binste]

Precise and succinct, great!