Compatibility of CBORType.Number in newer versions about cbor HOT 4 CLOSED

Here's a simple example to explain the situation i just described. Use the v4.0.1 library to run this

public static void Main(string[] args)
        {
            MemoryStream stream = new MemoryStream();
            EDecimal dec = EDecimal.FromString("34.6");
            CBORObject encode = CBORObject.FromObject(dec);
            encode.WriteTo(stream);
            stream.Flush();
            stream.Position = 0;
            var decode = CBORObject.Read(stream);
            bool old = decode.Type == CBORType.Number;
            // this returns true in v3.4.0 but false in v4.0.1
            // thus breaking functionality without compilation failures
            Console.WriteLine("CBORType.Number works " + old);
            Console.WriteLine("isNumber works " + decode.IsNumber);
        }

from cbor.

This library follows the semantic versioning rules, where backward-incompatible behavior can exist between major versions (such as between 3.x and 4.x), but not between minor or patch versions (e.g., between 3.1 and 3.2).

In version 4.0, CBORObjects were changed to no longer store objects directly as decimal fractions, bigfloats, or rational numbers, and CBORObject.Type now no longer returns CBORType.Number (which covered many of the same CBOR objects as the new IsNumber property does) for any CBOR object. The latter change, in particular, is not backward compatible with versions earlier than 4.0. In the future, CBORType.Number is expected to be removed in the next major version (version 5.0).

In addition, many properties and methods of CBORObject that dealt with numbers (such as AsEDecimal, Addition, etc.) will be deprecated in the 4.x series and many of them will be moved to the CBORNumber class, which stores numbers that CBOR will represent. These properties and methods, once deprecated, are expected to be removed in version 5.0.

from cbor.

I do agree that a major release is allowed to bring an incompatible change? but in this case the following happened:

1. CBORType.Number was deprecated
2. Behaviour changed
3. New major release

My question is: why not to remove Number in this major release and cause a build time failure?

Right now library clients still compile, but they are broken because the behaviour is different and it seems the only way to find out about this is through testing and reading change-log. While both of the options are valid, there's inherently a risk that there's not enough tests and change-log doesn't cover all of the changes. Essentially at this point it every client has to do something to make it work again, which is best enforced by a build time failure.

Right now there's a concern that Number change wasn't the only incompatible change and extensive testing has to be performed.

Could you please confirm whether Number was the only such change and what would you recommend to test in addition to Number related changes?

from cbor.

CBORType.Number wasn't the only incompatible change in version 4.0 that wasn't the removal of an API. Another such change is the Base64Padding property of JSONOptions, which now has no effect in version 4.0. However, at least the deprecation notice mentions that that property now has no effect. (A third incompatible change is that CBORObject's CompareTo method uses a different algorithm to compare CBOR objects.)

In any case, compiling code with a deprecated API will usually output a warning that the API is deprecated, and will include the deprecation notice in the warning. The mistake of the CBORType.Number deprecation notice was that it didn't mention that the value is now no longer returned for any CBOR object. The notice will change to mention this in version 4.1, or perhaps in a patch version 4.0.2.

Note also that code that compiles with warnings, including warnings of a deprecated API, is not necessarily code that "compiles correctly". There are ways to treat warnings as build errors (either all warnings or specific ones like the deprecation warning CS0618), such as via Visual Studio or via MSBuild's /warnAsError:CS0618.

from cbor.