Deprecation policies and BLOCKSDS_STRICT

[asiekierka]

Currently, deprecation in BlocksDS is done in one of three ways:

• using __attribute__((deprecated)) to mark types, variables and functions as deprecated,
• using registers_alt.h, a remnant from early libnds days, for unifying and cleaning up register names,
• removing the type, variable or function outright. That's no deprecation!

In addition, a lot of larger refactors are prevented by the goal to allow legacy codebases to migrate to BlocksDS with a minimum of fuss. While we'd like to be able to replace functions with more intuitive ones in some areas, this would require us to either remove the old functions (breaking this goal) or keep around both (confusing to the end user and allowing them to still rely on the legacy functions).

The JavaScript ecosystem, facing a not too dissimilar problem, has use strict as a way to forcibly disable some of the language's greatest warts. I propose a similar mechanism for BlocksDS:

• a new define, BLOCKSDS_STRICT is added, which is set by default (in the build script!) to the version of BlocksDS being released; for example, a ROM template in BlocksDS 1.3.0 would set -DBLOCKSDS_STRICT=10300.
• new deprecations and removed functions are gated by #if BLOCKSDS_STRICT < 10300 macros - this means that a 1.3.0 BlocksDS user creating a new program will not have access to them, but a legacy BlocksDS program will, for the time being.
• such deprecations and removed functions are removed from Doxygen - one can build an earlier version of the documentation from an earlier version of BlocksDS to see the documentation of legacy functionality, while new users will not be onboarded to it.

This allows breaking new code without breaking old code for as long as we want to; in addition, it provides a more user-friendly upgrade path: someone upgrading from 1.2.0 to 2.0.0, say, could bump BLOCKSDS_STRICT by individual versions, only fixing a few incompatibilities at a time and testing if their homebrew program broke on any of the steps. This, then, makes the migration process less daunting.

An alternate approach, which has fewer benefits but may also prove to be less logistically complex, is making a libnds2 alternative library and freezing libnds as is except for minor bugfixes - essentially, creating new libraries as a way to do API breaks. However, I fear that this will just lead us to a situation where we're discussing a libnds3 next year - IMO, a libnds2 would be best made after we run out of things to BLOCKSDS_STRICT-ify.

[asiekierka]

If we're actually moving forward with this, do let me know - I'll prepare a PR to introduce BLOCKSDS_STRICT as soon as possible (as described above: for 1.3.0, just as an #ifdef on top of existing deprecations).

[AntonioND]

Sure, you can go ahead.

[asiekierka]

#172
blocksds/libnds#109

[asiekierka]

The relevant PRs have been put on hold. Other proposals for tackling "a cleaner libnds" have been proposed, including "separating out libsysnds with the lower-level components of libnds, and making libnds itself something more akin to a middleware library, with libsysnds containing the drivers/hardware things/threading primitives/etc".