Haxe.unit.* and std library deprecation process

1

I noticed haxe.unit has been removed from Haxe 4’s standard library when I was greeted with this message trying to run unit tests:

Test.hx:1: characters 7-24 : Type not found : haxe.unit.TestCase

I understand the logic behind removing it from core, and GitHub - HaxeFoundation/hx3compat: Haxe 3 compatibility lib for Haxe 4 was one way to address compatibility (although you have to know it exists.) I’d like to suggest an alternative way to go about its removal, which hopefully can be used in the future on additional cleanup. I can point to OpenFL’s NMEPreloader deprecation as a great example of handling deprecation carefully. The important difference is that there’s an explicit transition phase, where both ways will work, before we remove one of them.

I’d like to see what people think. If the argument is “we should but we don’t have time”, :raised_hand: I volunteer to make the change myself :wink:

Step 1: Copy (don’t move) the package to a new library

Either put it in “hx3compat” or create a new “HaxeFoundation/unit” and copy the haxe.unit package there. (It’s possible to split files out of a git repo while maintaining their history.) The package now exists in both places.

Step 2: Apply a standard deprecation mechanism to haxe.unit.* types

If anyone uses haxe.unit.* from the main repo without including the new split out library, they should be shown a compiler warning; however, their tests should still compile and work. There are a couple ways to do this; OpenFL and HaxePunk have both done it in the past. Clearly deprecate it in the docs as well with the same hint.

The warning should specify exactly how to fix the problem: run “haxelib install hx3compat” and include it when you compile.

If you’re using the external version, it will shadow the std lib package and you won’t see the warning.

Step 3: Remove it later, in the next major version

When people have had plenty of time to make the switch, you can go ahead and remove the package from core.

1 Like
2

I like the idea of deprecating things carefully and giving a warning before introducing breaking changes, but it is a new major version of Haxe. When it is a major version difference in the language I don’t think it’s necessary to smooth out breaking changes. The reason you make it a new major version is because you have breaking changes.

That being said, in this case it is a simple difference of where the package is coming from so it may not be impractical do the change gradually like you said. Even though I don’t think it is necessary, I don’t think it could hurt. :wink:

3

You’re right that major versions in semver are for breaking changes, but breaking changes to APIs generally still go through a deprecation process. It’s the difference between users knowing what’s happening and what they need to do about it, and being able to do so on their own timeline, vs. seeing a “type not found” error and having to figure it out themselves. In this case it’s a very simple fix.

4

That makes sense, I know I don’t like getting errors without any meaningful explanation. It doesn’t really make sense to put a “this is going to be deprecated in Haxe 4” message in Haxe 3 either. That leaves the best place to put the message in the early versions of Haxe 4.