Release 1.0.1 because tag 1.0 reports 0.9.3 in dumb.h

[SimonN]

Hi, I have support for DUMB 1.0 in Allegro 5 while keeping its DUMB 0.9.3 support. To differentiate between 1.0 and 0.9.3, I use #if ((DUMB_MAJOR_VERSION) >= 1). This looks like the best way to handle the API breakage.

The Arch Linux DUMB package points to the commit tagged 1.0, it's good style to package only from tagged versions. Unfortunately, dumb.h in that commit still defines its version as 0.9.3.

Please increase 1.0.0 to 1.0.1 in the header, then tag that new commit as 1.0.1. If you prefer 1.1 or any other 1.y.z, that's perfectly fine, too.

@SiegeLord, Allegro 5 maintainer, agrees that such a new tag would be the best solution. I'll email the Arch DUMB and Allegro 5 package maganager afterwards and coordinate.

[katajakasa]

There was talk about releasing 2.0.0 here: #38

[SimonN]

2.0.0 would be good, too -- I'd have no problem updating my code for that.

I've read #38 earlier this week, even. I've still suggested 1.y.z because it wasn't clear whether everything for 2.0.0 was in place yet, whereas any commit could be tagged 1.y.z without breaking (assuming the 1.0.0 in dumb.h is adequate).

[Rondom]

Question whether it is worth branching off and changing that header. Arch is a rolling release distro and would be happy to package 2.0.0 quickly, I guess. I have not done a complete survey, but if the majority of distributions are still on 0.9.3, there is no big win in supporting dumb1.0.1 in Allegro, if we are able to release 2.0.0 in a few weeks (that's my estimation, feel free to agree or disagree).

[SimonN]

Under normal circumstances, I'd agree immediately -- waiting some weeks for 2.0.0 would be no problem at all, because all legacy code could still play music, and we should take enough time to test & review all breaking changes.

But the situation on Arch is dire: Tracked music in Allegro 4 and 5 is broken. A tag would help, or we could guess the DUMB API with compile-time tricks.

Arch's Allegro 5 package isn't offering any tracked music at the moment. For the longest time, the DUMB Arch package hard-depended on Allegro 4, which was considered unacceptable as an Allegro 5 dependency. Some Arch games even relied separately on A5 and DUMB with A4 in tow, playing music through A4.

A month ago, Arch's DUMB advanced to DUMB-git-tag-1.0: That DUMB has the 7-pointer DUMBFILE_SYSTM and 2-argument .mod-playing API for 1.0, but its header reports 0.9.3, and it has no A4 support. It's a troublesome combination, but since it's the newest tagged version, it's preferred according to Arch packaging guidelines.

This broke music on all Allegro 4 games and the Allegro 5 games with the fallback. A5 still cannot play music easily through DUMB because there is no reliable way to detect the tagged-1.0 DUMB: That DUMB's header reports 0.9.3, wrongly indicating the 5-pointer DUMBFILE_SYSTEM and 1 argument to .mod-playing.

Please consider a tag, so we can package a checkable DUMB version.

As a workaround, Allegro could employ some tricks at compile-time or in the build system to guess the installed DUMB API. That would be hackish, but it gives you the option not to tag, yet allow music in Allegro on Arch.

---

I've looked through the history of the API since git-tag-1.0. If you decide to tag before 2.0.0, a new version of 1.1 would be more appropriate than 1.0.1. The most recent API addition was in commit b6c4ec4 in 2016-02-04, this added new functions and deprecated duh_render.

[Rondom]

For clarification: I meant 1.0.1 to be 1.0.0 + one commit to correct the version in the header-file. This is the lowest-effort and lowest-risk way. What I meant was that there is no need to encourage the proliferation of an older version when a newer, compatibility-breaking version is near. Also note that I am in no way speaking for kode54 or the dumb-project, it was just my opinion on how the spend efforts.

I assume your code is not inside upstream allegro5,yet. So upstream-allegro only supports 0.9.3. I understand from your code-comments that 2.0.0 deprecates some functions and I thus do not see if it is really necessary to maintain support for three different dumb-versions/APIs in Allegro 5 (0.9.3, 1.0.1, 2.0.0) given that 1.0.0 is not that widespread, yet.

What speaks against fixing the breakage inside the Arch-libdumb-pkg instead of Arch-liballegro5-pkg (maybe using a separate define if you want to be super-compatible with others), so users who did not have mod-playback in their games for a month on Arch can at least have it within the next two or three weeks?

[SimonN]

Thanks for the detailed insight and judgement.

My judgement was that the 1.0 API had already been much more common: The 7-pointer DUMBFILE_SYSTEM is from January 2013. The git tag 1.0 is from January 2015 and the header that reports 1.0 is from July 2015. Everything in the 2 or 2.5 years of difference would have already relied on the 1.0 API.

It's a tricky decision, I'll sleep on it for a couple days. Maybe indeed wait, and have good documentation on how to resolve the deprecation.

Yeah, my code hasn't been merged into upstream A5 yet, because I'd like to have a decision here first.

[Rondom]

Maybe my impression is also wrong, but the last time I checked none of the released versions of Linux-distros had switched to this fork, but maybe this has changed in the meantime.

[SimonN]

@kode54, what are your plans on the API in the next weeks? When can we tag the API as 2.0?

I'd really like to push for stabilization. It's fine to add functions afterwards in 2.1, 2.2, etc., but not remove any from the 2.0 API without bumping the major version number, and DUMBFILE_SYSTEM should stay exactly the same throughout all of 2.*.

[kode54]

I had only planned to fix bugs, not break any API. Tagging as 2.0 should be fine, so long as I've cleared away all the bugs. I had someone fuzzing the library for me, not sure what his current status is now that I've fixed all of the crashers he sent me.

[SimonN]

That's awesome news! Then @Rondom's suggestion is best, work towards 2.0, and let's not re-tag a 2015 version as 1.0.1.

In case you find more bugs, it's perfectly fine to have versions 2.0.z with more bugfixes.