On Release Versions

Posted: September 7, 2018
By: Nate Finch

If you’ve been using Mage for a while (thank you!) then you may have noticed something odd in the last week. Mage was previously at v2.3.0… but now the most recent release is 1.3.0 (released today!). So, yeah, sorry if this makes your life difficult, and I know it’ll cause problems for some people. Hopefully most people have mage vendored and can go about their business until they need something new, and then it shouldn’t be a big deal to just take whatever the newest release is, even if it “looks” like it’s an earlier release.

The reason for this is two things: the major motivating factor is go modules support. To enable support for go modules, if you are on version 2 or higher of your code, then import paths need to be appended with /v2. i.e. to import github.com/magefile/mage/mg from a v2 tag, you’d write the import as import "github.com/magefile/mage/v2". With a go.mod that declares the module to be github.com/magefile/mage/v2, the go 1.11 tool understands that the /v2 on the end is not a real subdirectory, but just references the version of the module, and it’ll strip that off. This understanding was backported to go 1.10.3 and go 1.9.7. But any other versions of the go tool earlier than 1.11 will expect there to actually be a v2 directory in your repo for this code.

Since I really want to keep Mage as backwards compatible as possible (CI runs tests with versions as far back as 1.7)… I didn’t want this headache. I also didn’t want everyone to have to make their import statements say /v2. Mage’s libraries are and always will be backwards compatible. The tags on the repo previously were not intended to be semantic versions. In fact, I had intended to simply make each new release a major version specifically to make it clear that these aren’t semantic versions (just like Chrome is on v70 right now). However, I wasn’t very careful, and some of my tags were in semantic version format (i.e. v2.2.0) and thus the go 1.11 tool took those to mean that the repo is on v2.

What to do? Mages users right now are still somewhat limited… looking at github there’s maybe a hundred or so repos using Mage (again, thank you!).. but I hope in the future that this will grow manyfold. In order to make the many years and hopefully many orders of magnitude of users’ lives easier, I decided it was best to rip out the v2.x tags and reclaim the title of v1. This keeps import paths the same as they were in v1.10 and before.

From now on, all releases will be in semantic versions of ever increasing v1.x.x.

Although I know this will cause some issues, I hope that the pain will be brief and slight…. and the ability to stay backwards compatible with earlier versions of Go and to make future development easier is worth it in my opinion.