From fa6c1217f253ddc0ac94e99a7b22469acc744a57 Mon Sep 17 00:00:00 2001 From: ISSOtm Date: Thu, 30 Jan 2025 10:04:04 +0100 Subject: [PATCH] Finish backcompat part IV --- content/blog/backcompat/part4.md | 45 +++++++++++++++++++++++++++++--- 1 file changed, 41 insertions(+), 4 deletions(-) diff --git a/content/blog/backcompat/part4.md b/content/blog/backcompat/part4.md index c91294d..02cc12f 100644 --- a/content/blog/backcompat/part4.md +++ b/content/blog/backcompat/part4.md @@ -26,14 +26,45 @@ This is, on its face, uncontroversial to fix; however, doing so required[^requir Every other change merely falls somewhere else on the "benefits vs. discontent" scale. -TODO: +We try hard, however, to mitigate the pain, with a three-pronged approach: -- Deprecations -- "Crater" runs -- Old versions +- **Deprecations**: We deprecate every feature for at least one version before removing it. + + {% admonition(kind="note", title="exception") %} + There has been one exception, the 0.6.0 [trigonometry function changes], which turned out to be a backwards-incompatible change we missed. + Again, we're only human 😛 + {% end %} + + This has mostly succeeding in avoiding surprising breakage, with the exception of the `-h` flag (more on that in a bit); however, some have pointed out that the warnings are still annoyances like errors. + I disagree: a warning can be temporarily ignored while progressively fixing up a codebase, but a hard error forces you to fix everything before you can even check out the results. + + As for [`rgbasm -L`, AKA `--preserve-ld`], it turned out that the deprecation mechanism we chose (warn on first trigger, introduce `-l` / `--auto-ldh` to silence it) annoyed people who were trying to support 0.6.0 and 0.5.0 at the same time: before 0.6.0, `-l` would be a hard error, but after it, its _absence_ would produce warnings. + In hindsight, I think we should have not provided those flags, and instructed those projects to [use `-Wno-obsolete`] (or [maybe `-w`]?) while they wished to keep supporting 0.6.0. + +- **Checking downstream projects**: We integrated several projects using RGBDS into our CI, and thus, attempt to monitor the impact of changes we make. + We also submit patches to them when breakage is made, both to evaluate how involved the upgrade process is, and also to attempt to repay the technical debt we create ourselves. + + Note that, in particular, projects that are not brought to our attention (not to mention private projects!) + Hence, I get quite 😒 when someone complains that $CHANGE breaks a project of mine that I haven't released!. + Since RGBDS is a project made available publicly for free, I don't consider it fair to have to take into account what people keep to themselves. + If we _were_ being paid somehow, then the dynamic would be different. + +- **Archive of old versions**: Finally, we make sure to keep an archive of every version that has been released thus far _and its documentation_ [readily accessible](https://rgbds.gbdev.io/docs). + + So, even if we are not updating it anymore, a version that your project has worked with, will keep working all the same. + All you need to do, is **document which version of RGBDS you are currently using**, for example in your project's README.[^guesstimate] + + Of course, then it means that you wouldn't be getting the latest features without some extra effort; please re-read [the previous part's conclusion](@/blog/backcompat/part3.md#conclusion) for a note about that. [^required]: If you have already thought of some way the change could have been implemented backwards-compatibly, please hold on to that thought for now, I'll address that further down. +[^guesstimate]: For projects which haven't documented their version, checking the latest version available as of the first commit is usually a good (first) guess. + +[trigonometry function changes]: https://github.com/gbdev/rgbds/pull/1060 +[`rgbasm -L`, AKA `--preserve-ld`]: https://rgbds.gbdev.io/docs/v0.6.0/rgbasm.1#L +[use `-Wno-obsolete`]: https://rgbds.gbdev.io/docs/v0.6.0/rgbasm.1#Wno-obsolete +[maybe `-w`]: https://rgbds.gbdev.io/docs/v0.6.0/rgbasm.1#w + ## "You could have done better!" Some critics point out that the changes could have been done while causing less pain. @@ -58,6 +89,12 @@ I hope this explains why I tend to get a little jumpy and bitter when my[^our] w [rgbenv]: https://github.com/gbdev/rgbenv#readme [contrib]: https://github.com/gbdev/rgbds/tree/master/contrib +## Future directions + +rgbfmt, or other upgrade scripts + +Regexes + ## Conclusion With all of that said, and the last section especially getting a little personal—guilty as charged, I needed a little venting—I want to leave on a more positive note, and provide guidance on how to avoid such difficult situations in the first place.