SDL_Version.h visibility and intermediate versions bumps

[ocornut]

A few niggles I always had with SDL versioning, which I thought might be useful mentioning:

It's not absolutely trivial to find which version of you are using.

• You have to dig and find SDL_Version.h to find which versions of header you are using.
• Occasionally, IDE shenanigans means you can't open SDL_Version.h trivially from SDL.h

In Dear ImGui, full version information appears near the top of imgui.h (line 30, visible from fist page) + every source files has a simplified version number at the top. I believe it wouldn't hurt and wouldn't be a big maintenance issue if SDL.h has a highly visible copy of the version number in comments. EDIT additionally, SDL_Version.h could intentionally be moved to being the first include, to increase its visibility and access to the full thing.

Intermediate breaking changes don't have immediately usable version bump. e.g. 94cbaaa

• You have to wait for a tagged release in order to be able to support a change or feature because you often need a value to check on.
• Otherwise it is impossible for a software or library to be supporting intermediate versions, therefore discouraging people to pull and build from sources if they rely on other software using SDL. Considering the current pre-release situation of SDL3 I would assume quite a large of users are pulling from sources, and this strategy creates lots of breaking changes that are hard to support.

In Dear ImGui, I always increase the minor-most version number (which for me is described as a single integer, 5 digits - I would prefer it to be 6 digits), which might be roughly be equivalent to SDL_PATCHLEVEL or even a "lower" number.

#define IMGUI_VERSION       "1.90.7 WIP"
#define IMGUI_VERSION_NUM   19061      // any small breaking change or new feature increases this, allow for trivial features check

To be clear, I'm happy to update and catch up with breaking changes in SDL2/SDL3 backends, my problem is that if e.g. I catch up with the one linked above, I would break build for users for 3.1.2 Preview or older versions. So I am left with the choice of:

• keeping build broken for people who pull from sources after 3.1.2 preview and before 3.1.3 preview.
  or:
• fixing build for people pulling from sources, but breaking it for people who downloaded 3.1.2 preview.

While I realize the issue may seem minor, I worry that it has a net effect on people willing to trust pulling from sources. I generally think it is GREAT that people can pull and build from sources, it means more early adopters, more feedback, more likely developers contributions, etc.

[slouken]

Thanks for the feedback!

FYI, the odd numbered builds are unstable and do not have API/ABI guarantees. That said, we're only a month or two away from ABI lock, so hopefully this is temporary growing pains for SDL 3.0.

I like the idea of putting the version in SDL.h, @icculus, thoughts?

[slouken]

(in the meantime, I'll bump the version for you!)

[ocornut]

It wouldn't mean you have to maintain any more API or ABI compatibility, but it provide a little extra metadata and convenience. I do appreciate the special timeframe circumstance toward SDL 3.0 release, but you could argue the same logic will apply between any two of your future release. It's especially valuable if the releases ends up being spaced out making larger number of users pull from sources to grab some feature/fix they want that's not in a release yet.

In my case I also found it useful that increasing the minor-most version number very often made it that me and users can conveniently narrow the version they use to a much smaller range of commits/time based on a (highly visible) single number.

(But I suppose this is more useful due to the fact that dear imgui rather aggressively encourage people to build from sources, whereas a larger majority of SDL users would grab precompiled packages or from a package manager).
(Also not so many third-party libraries are users for SDL API, so this problem doesn't happen to too many people)

[slouken]

@icculus and I discussed it, and our view is that if you're targeting a stable release (e.g. 3.2) you won't need to worry about incompatible API changes. If you're targeting a development release (e.g. 3.3) you should always target the latest changes in GitHub, and so should your users. The 3.1 preview releases are a special case, where we want to get API changes out in front of users for feedback, but in general we won't be doing that for future development branches.

git submodules are a handy way of advancing dependencies on unstable code in an organized non-breaking way. They include the git hash of the remote repo that you are compatible with, and when you update your code you can update the git hash associated with the submodules, so your users always have working and compatible versions of unstable code. The SDL satellite libraries use this to lock to compatible versions of their dependencies, if you're checking out from GitHub.

[slouken]

If your users are on a 3.1 preview release and you've updated imgui past that, please encourage your users to grab the latest code from SDL git. The preview releases are not intended to be stable code to develop on, they're just that - previews of a moving development target that is getting closer to release, but not quite there yet.

[ocornut]

Thank you both for looking into it.

In general I am targeting any possible release that users might want to use, which include unstable versions, but I don't mind the restriction that when we target unstable versions we should generally aim to target very-latest.

I hope you'll still move forward with moving the most obvious versions stuff on top of SDL.h :)

[slouken]

In general I am targeting any possible release that users might want to use, which include unstable versions, but I don't mind the restriction that when we target unstable versions we should generally aim to target very-latest.

That sounds great.

I hope you'll still move forward with moving the most obvious versions stuff on top of SDL.h :)

Yep, thank you for the suggestion!

[smcv]

I always increase the minor-most version number

One way to think about this is that every time you do this, you're effectively making it into a new micro-version release - and the only thing distinguishing between that and a "real release" is that you probably don't produce release artifacts (source or binary tarballs) for every commit, and when you're doing a "real release" you probably do more testing/QA before saying it's ready.

This works for you as the sole maintainer, but third-party contributors (or packagers who might backport a bug fix) can't really do this, because you control the versioning space, and anyone else assigning new version numbers would be creating an incompatibility. So there will sometimes still be changes that can't be represented in that version number, whenever someone applies a local change, or backports a bug-fix patch into their LTS distribution, or similar.

I think the only thing we can say with any certainty is that if SDL identifies itself as version x.y.z, then it is aimed to be at least "as good as" version x.y.z - it has all the features of x.y.z, and at least as many bug fixes as x.y.z (but maybe more). If a feature or a bug fix has happened since the most recent tagged version, then you're right that there's no way to detect that from the version number, but I think that's a reason to ask maintainers for a new micro-release, rather than a reason to proactively assign version numbers to every intermediate commit just in case.

SDL 3.1.x is different because SDL 3.1.x is explicitly not API- or ABI-stable yet, but from 3.2.0 onwards, it will be back to the same stability pattern that 2.x has.