Provide documentation on breaking changes (upgrading from 1.2.6 to 2.0) and how to deal with them

[Daniel Trierweiler]

I know this isn’t a technical issue, but we are currently preparing to upgrade our projects to Delphi 12, including an upgrade to Spring4D, in order to tackle the warnings that would now emerge in generic classes.

In doing so, we found a lot of breaking changes, like the introduction of a custom TPair class (which we had to disambiguate using the FQDN), removed classes (like TOrderedDictionary, which we tried to replace with the dictionary returned by the factory CreateDictionary), or the removal of default constructors and the initialization of the collection classes being moved to AfterConstruction (which makes it impossible for us to initialize a list in the constructor, or provide a simple copy constructor. Moving this to factory methods right now). Most problematic about these last changes is, that they won’t break the compilation, but only at runtime.

Up to now, we still don’t have an actually running build and are unsure which change we have overseen. We couldn’t find any documentation in this regard though. Could you please point us to such a documentation (or create one)?

(We were also a puzzled to find only a single reference to Delphi 12 in the Spring.Inc, which doesn’t seem to add support for it, but would only suppress these warnings - including a hint that this is going to be fixed with V2.0 ..)

[Stefan Glienke]

• TPair introduction - in fact that one was the only reason you ever had to add System.Generics.Collections to your uses - with 2.0 you can eliminate it entirely (if you are still using stuff from System.Generics.Collections I suggest migrating to exclusively use Spring) - thus there is no need to fully quality
• removal of classes and/or changes to their internals (including removal of some ctors and moving things to the factory methods) - I always communicated that the implementing classes are that: implementation details. If you inherit from them and the interfaces and add your own methods to them it’s up to you to solve these problems - also beta has been out for a very long time exactly for this reason: to give people time to try out things, report any issues and ask me for assistance. The first RC was in Feb 2023 which was after the big internal refactoring landed in develop and since then there only have been some minor breaking changes. I simply cannot meet the goals I have set for this library when making it backward compatible for every eventuality.
• Delphi 12 - as you may know Spring is using the Jedi.inc which is written in a forward-compatible way and any conditionals in the Spring source code are written in a way that unless there is a breaking change in some new Delphi version it just works. I could have updated to the by then latest Jedi.inc which includes the defines for Delphi 12 but there simply was no reason yet. As you can also see the warning suppressing is only for 1.2 which contains the code that causes these warnings. 2.0 does not raise any warnings because those have been fixed in 9c61d28.

‌

[Stefan Glienke]

Addendum: Git’s merge “smartness” got me - that IFDEF VER360 should not be there anymore in the Spring.inc because it’s not needed anymore

[Daniel Trierweiler]

:D Thank you git. And sorry, if that came across wrong. I don’t want to keep you from making breaking changes. I’m completely fine with that, if it is required to reach a goal. And I’m also fine with adjusting the classes in my project for sure.

My problem with that is still though, that I don’t even know what changes I have to take care of, because I can’t find any documentation on them - or on the goals you’ve set for this library (or the 2.0 release, or the release candidates).

The changes I mentioned above are more or less obvious - I can at least see that something is broken either by just compiling or quite early in the execution of my project (even though I wouldn’t expect this to apply to all projects). Having some sort of release-notes would help me to pinpoint the less obvious changes and help to estimate the complexity and expenses of an update.

‌

[Stefan Glienke]

Spring4D 2.0 Releasenotes - WIP

[Daniel Trierweiler]

That’s great, thank you very much!