SMAPI - Stardew Modding API

SMAPI - Stardew Modding API

Utility
971k Downloads

Add deprecation warnings

Pathoschild opened this issue ยท 3 comments

commented

Add a mechanism for SMAPI to detect when a mod uses an obsolete method/field/property, and log a warning like this.

[02:33:51] [WARN] ModName used Extensions.AsInt32, which is deprecated since SMAPI 1.0. It will work fine for now, but may be removed in a future version of SMAPI.

To do

  • When loading mods, keep track of their assemblies.
  • Add a simplified method to log a deprecation warning.
  • When a deprecation warning is logged, examine the stack trace to determine which mod is at fault (by finding the first stack frame occurring in a mod assembly).
    • If the mod at fault can be determined, show a pretty message.
    • Otherwise show a stack trace.
  • Only show one deprecation warning per method per mod.
commented

Done in the upcoming 1.0 release; see draft guide for solving deprecation warnings.

commented

The first feedback from 1.0-alpha suggests the deprecation warnings are too verbose; every mod will have at least two, since the Authour manifest field and Entry method were deprecated.

Here's a more nuanced system where deprecation happens over several versions:

version deprecation level
x The interface is newly deprecated.
Write deprecation warnings to the log file, but don't show them in the console.
x + 1 Log a grayed-out message to the console.
x + 2 Log a warning to the console.
x + 3 Log an error to the console indicating it will break soon.
x + 4 Remove the interface.

We could optionally split SMAPI releases into two, like SMAPI 1.0 and SMAPI 1.0 for developers. The latter would include the intellisense files and always show deprecation notices.

commented

Done in the next 1.0 build. Deprecations now have three severities:

severity description
notice The interface is deprecated, but mod authors have time to update their mods. Nothing is reported to the console, although deprecation messages are shown in the log file.
info Mods should no longer use this interface. Debug-level deprecation messages are shown in the console.
pending removal Mods should no longer use this interface. Warning-level deprecation messages in the console indicate the mod will break soon if it doesn't update.

The following interfaces are deprecated in 1.0:

severity interfaces
notice Mod.Entry(object[]), Config and related properties, and Version.VersionString.
info Extensions class.
pending removal Extensions.ToSingular (non-generic version NOP'd in 0.39.3).

Starting from the next 1.0 alpha release, each release will be available in two versions (e.g. SMAPI 1.0 and SMAPI 1.0 for developers) per my previous comment.