Discussion: Deprecation

[ithinkandicode]

Many of the changes outlined in #153 would be breaking, so for those, and for the future in general, it would be good to have a standardised way of handling deprecated method calls.

Suggestion

# A method has changed its name/class
func deprecated_changed(old_method: String, new_method: String, since_version: String):
	ModLoaderUtils.log_fatal(
		str(
			"The method \"%s\" has been deprecated since version %s. " % [old_method, since_version]
			"Please use \"%s\" instead. " % new_method,
			"The old method will be removed with the next ModLoader update, and will break your code if not changed. "
		LOG_NAME
	)

# A method has been entirely removed, with no replacement
# (should never be needed but good to have just in case)
func deprecated_removed(old_method: String, since_version: String):
	ModLoaderUtils.log_fatal(
		str(
			"The method \"%s\" has been deprecated since version %s, and is no longer available. " % [old_method, since_version]
			"There is currently no replacement method. ",
			"The method will be removed with the next ModLoader update, and will break your code if not changed. "
		LOG_NAME
	)

# Freeform deprecation message.
# Allows you to add a deprecation comment without the above conventions
func deprecated_message(msg: String, since_version: String = ""):
	if not since_version == "":
		ModLoaderUtils.log_fatal(str(msg, " (since version %s)" % since_version), LOG_NAME)
	else:
		ModLoaderUtils.log_fatal(msg, LOG_NAME)

Example Usage

class_name OldClass

func foo(var1, var2):
	deprecated_changed("OldClass.foo", "NewClass.bar", "6.0.0")
	NewClass.bar(var1, var2) # Still allow the code to run outside of the editor

Keeping Old Files

If an entire class becomes deprecated, we can create a directory called deprecated and put that class there, with its contents just being all its old func definitions with deprecated_changed used for each one.

[Qubus0]

Yeah that seems good. I would make the message a bit harsher, since many beginners do not know what "deprecated" means.

"Calling this method with "%s" has been deprecated. Use "%s" instead. The method will be removed with the next ModLoader update and will break your code if not changed."

Also, not all changes might be as simple as "moved from one class to another", so we could also use a deprecated() method with a freeform message

[ithinkandicode]

Good call @Qubus0. I've updated the methods to mention that. I've also added a version string to the args, with it being optional for the freeform method.

[Qubus0]

Yep. This sounds exactly like what we need. 🚦🟢

[ithinkandicode]

• Closed by: feat: ✨ API: Add methods for deprecation + API Folder #156