Version tags for Dub

[jacob-carlborg]

Dub is about to remove/deprecate the use branches for dependencies in favor of only using version tags. It would be great if we could start adding version tags. Preferably using semantic versioning: http://semver.org/.

[SiegeLord]

I'm not quite clear how this would work here. In principle the only changes that are being made are DMDFE maintenance/occasional bug fix. Is the idea that I would tag each one of those commits with a version tag (with an incrementing minor version)? Should I tag it every couple of changes? Every couple of months? Is it truly useful and meaningful to have these 'releases'/version tags?

One further issue is that occasionally DMDFE introduces such bad regressions that I disable some API entries for that DMDFE version... would that imply I need to increment the major version in this case? This seems like a general issue of using semver given a shaky foundation. Additionally... even things like #73 in principle constitute a backwards incompatible change (e.g. some code relied on typeof or whatnot)... is there a widely accepted definition of what constitutes API stability in D world with D's introspection abilities? Perhaps this all just means that the leading version should be '0'.

Personally, I don't care what it is since I don't use Dub... but I also don't necessarily want to lie that I use semver and while not following its guidelines, nor do I want to necessarily screw things up for people that do use Dub by continuing the haphazard work flow I've been following.

[jacob-carlborg]

I'm not quite clear how this would work here. In principle the only changes that are being made are DMDFE maintenance/occasional bug fix. Is the idea that I would tag each one of those commits with a version tag (with an incrementing minor version)? Should I tag it every couple of changes? Every couple of months? Is it truly useful and meaningful to have these 'releases'/version tags?

I have been thinking of that myself. I don't think it's really useful to have because Tango itself wouldn't change, unless to fix a breaking change in DMD. But since Dub will require that I don't know what else to do, besides not using Tango via Dub.

Since Tango now is basically only changed when a new release of DMD is out I would create a new version tag per release of DMD (if any changes have been made). You can even do something like 1.0.0+dmd-2.065.0 to indicate which exact version of DMD this version corresponds to. Note though that everything after the plus sign is only metadata and will be ignored when comparing versions.

One further issue is that occasionally DMDFE introduces such bad regressions that I disable some API entries for that DMDFE version... would that imply I need to increment the major version in this case?

Yes, if strictly following semantic versioning.

This seems like a general issue of using semver given a shaky foundation. Additionally... even things like #73 in principle constitute a backwards incompatible change (e.g. some code relied on typeof or whatnot)... is there a widely accepted definition of what constitutes API stability in D world with D's introspection abilities?

Yeah, it's problematic. Although I wouldn't count the introspection abilities. I mean, in D it's possible to access private symbols, which is exactly what you're supposed to be able to change, according to semver, and only increment the build version.

Perhaps this all just means that the leading version should be '0'.

That's an alternative. But it seems a bit weird to be stuck at major version 0.

Personally, I don't care what it is since I don't use Dub... but I also don't necessarily want to lie that I use semver and while not following its guidelines, nor do I want to necessarily screw things up for people that do use Dub by continuing the haphazard work flow I've been following.

I understand.

In the end I get the felling that most D project that provides an API of some kind will have the same problem. The difference is that those projects would probably change anyway.

If it was me that decided I would add a new tag every release of DMD (if any changes have been made) and increment the versions according to semver. Yes, that would probably result in often increasing the major version.

[SiegeLord]

So what I'm thinking is doing this:

Have two branches, d2port which is what it is today, and then a branch per minor-version, with tags into that branch. The minor version gets bumped each DMDFE release, and perhaps if there's a legitimate new feature added. This branch can get stuff back ported into it, which would immediately trigger a patch version bump and another tag. So it'll look something like this:

branch: 2.066
tag: 1.0.0+2.066 - Initial DMDFE 2.066 release
tag: 1.0.1+2.066 - Some bug fixed between DMDFE releases
branch: 2067
tag: 1.1.0+2.067 - Initial DMDFE 2.067 release

The major version is fixed arbitrarily at 1 and won't be changed in the immediate future. I can start doing this once 2.066 is released. Does this sound good to you?

[SiegeLord]

I should say that the idea here is that you can sort of use the semver range version specification in dub for something useful, but without necessarily following semver to the letter (which I believe nobody does in the D community).

[jacob-carlborg]

What is the reason to fix the major version?

[SiegeLord]

I guess I have no reason. I just glanced at the dub repository and it nobody else was doing that... in the scheme above I'd imagine bumping the major version if some functionality was legitimately changed.

[jacob-carlborg]

I just glanced at the dub repository and it nobody else was doing that

To be sure of that you would need to go through all changes between releases to see if they added breaking changes or not.

in the scheme above I'd imagine bumping the major version if some functionality was legitimately changed

I guess it depends on if Tango should follow the semantic versioning scheme properly or not. Just because the other projects don't follow it doesn't mean it's the right thing to do. The documentation for Dub says projects should follow semantic versioning.

[SiegeLord]

I'm really not sure it is practical to follow semver strictly. Ignoring practicalities, the most sane solution is to create a new package that starts a 1.0 with every dmd release. That way DMDFE releases don't matter, and the version truly represents the backwards compatibility guarantees the library provides.

I don't think a separate package per DMDFE release is the model dub is going for though... would the registry really like to have N different tango-2.0xx packages?

So abandoning the 'perfect' solution, I could increment the major version instead (as per semver) and just never backport major version affecting changes to older tango versions. I.e. something like this could/will happen:

1.0.0+2.066 - 2.066 released, causing changes
2.0.0+2.067 - 2.067 released, causing changes
3.0.0+2.067 - Some change not associated with DMDFE. Cannot be backported to 2.066-compatible Tango!

So that strict interpretation of semver doesn't work either (although it is an option... it's not like I actively backport things).

The last alternative is not to follow semver, but leverage the version selection mechanism available in dub, which is what I described earlier.

[jacob-carlborg]

I'm really not sure it is practical to follow semver strictly. Ignoring practicalities, the most sane solution is to create a new package that starts a 1.0 with every dmd release. That way DMDFE releases don't matter, and the version truly represents the backwards compatibility guarantees the library provides.

Why would there be a new package for every DMD release? Are you expecting to support a version of Tango, with backwards compatible changes, for every DMD release? That seems quite a lot of work to do.

I don't see what is so hard. There should only be one package "Tango". The version is increased when there are changes in the code and we want to make a new release. The most likely reason for a change would be a new release of DMD requiring it. If there is a backwards incompatiable change in the API the major version is increased. If a change is required that doesn't change the API the build/patch version is increased, and so on.

I don't think a separate package per DMDFE release is the model dub is going for though... would the registry really like to have N different tango-2.0xx packages?

No, absolutely not.

So abandoning the 'perfect' solution, I could increment the major version instead (as per semver) and just never backport major version affecting changes to older tango versions. I.e. something like this could/will happen:

1.0.0+2.066 - 2.066 released, causing changes
2.0.0+2.067 - 2.067 released, causing changes
3.0.0+2.067 - Some change not associated with DMDFE. Cannot be backported to 2.066-compatible Tango!

Of course you cannot backport an API breaking change. By definition, of semver, it requires you to increase the major version.

Or you're referring to using the latest version of Tango with an older version of DMD? Yeah, that might be a problem. It all depends on the changes that were required between 2.066 and 2.067. Sometimes that changes that need to be done in Tango are backwards compatible, sometimes they're not. There are workarounds that sometimes work, like a static if checking for a specific version of DMD or implementing all of toHash, opEquals and opCmp as per the latest issue with 2.066.

In the end, I think that the user of a library (Tango) eventually have to make a choice. Either stay with an old version of Tango and DMD or update to the latest version. You cannot support both old versions and new versions of DMD forever. That happens all the time with libraries in other language, although it might happen more often with D.

I know form my work with Ruby that some libraries do provide multiple packages for different version of the language, i.e. one for 1.8 and one for 1.9. But that is more in the scale of one for D1 and one for D2 then one for 2.065 and 2.066. But that is rather a problem with the release process and versioning scheme of D. Because any major changes can happen between two releases.

[SiegeLord]

Why would there be a new package for every DMD release? Are you expecting to support a version of Tango, with backwards compatible changes, for every DMD release? That seems quite a lot of work to do.

I was thinking of supporting the current version and the previous version.

I don't see what is so hard. There should only be one package "Tango". The version is increased when there are changes in the code and we want to make a new release.

Essentially the issue is that I'd prefer not to force everybody to immediately jump ship to the newest dmd version just because Tango managed to do it. I guess my proposal might be going a bit overboard then, and it's not like I have tried to do that very strongly.

1.8 and one for 1.9

Hehe, looks like D is not the only language making giant changes between minor releases ;).

Anyway, I think you're right and it's best to keep this simple. Once 2.066 comes out I'll just tag the corresponding commit as 1.0.0 and we'll go from there.

[jacob-carlborg]

I was thinking of supporting the current version and the previous version.

For the latest version of Tango?

Essentially the issue is that I'd prefer not to force everybody to immediately jump ship to the newest dmd version just because Tango managed to do it. I guess my proposal might be going a bit overboard then, and it's not like I have tried to do that very strongly.

I understand your reasoning but currently the only reason Tango is changed is when a new version of DMD is released. That means if you don't want to move to a later version of DMD there's no reason to use a later version of Tango.

Hehe, looks like D is not the only language making giant changes between minor releases ;).

Actually, Ruby doesn't follow semver, at least not back then. Ruby 1.8 and 1.9 are major versions of the language. It's like D1 and D2 or C++98 and C++11. On top of that there are several minor releases and patch releases like 1.9.2-p180.

Anyway, I think you're right and it's best to keep this simple. Once 2.066 comes out I'll just tag the corresponding commit as 1.0.0 and we'll go from there.

Awesome.

What you could do, if you want to, is to keep a branch per version of DMD. If there's a change in Tango that is unrelated to DMD you could backport that to one of the branches for a specific release of DMD without tagging it. It won't be available in Dub but you can still access it the old fashion way.

[SiegeLord]

Here it is: https://github.com/SiegeLord/Tango-D2/releases/tag/1.0.0%2B2.066

I assume whoever deals with the dub registry will pick it up one day.

[jacob-carlborg]

Here it is: https://github.com/SiegeLord/Tango-D2/releases/tag/1.0.0%2B2.066

Awesome, thanks.

I assume whoever deals with the dub registry will pick it up one day.

It should happen automatically.

[jacob-carlborg]

The version tag actually needs to begin with a "v". So it would become v1.0.0+2.066. It's the Git convention, which Dub is what follows.