Switch to Semantic Versioning

For developers using the Construct 2 Javascript SDK

Post » Mon Apr 15, 2013 6:51 am

So I've been dealing with the SDK for a project I'm working on, and something caught my eye. Namely, the versioning:
[quote]version
This is a float in the format x.y which identifies the version of your plugin. [emphasis added] You should keep this updated whenever you make a new release. Construct 2 uses it to verify projects are compatible when opening. For example, Construct 2 will show a warning if a project was saved with version 2 of a plugin, but is opened with version 1 of the plugin installed.[/quote]
Using a float is not exactly a great system for versioning. You could consider it as a major.minor scheme, but if compared as a float you can easily lock yourself into having to do new major revisions every 10 updates if you limit yourself to a single decimal (1.8, 1.9, uh oh, 2.0), or at some point if you don't want to increase the major version number you'd end up doing version numbers like 1.992 or so. Not exactly ideal.

As such, I'd like to suggest that Construct 2 switches to semantic versioning for addons. It would remove the pitfalls mentioned earlier, and also bring, well, semantics, to addon versioning. For example:

- Addon Version 0.X.X means that the public API (in Construct 2's case, ACEs and parameters) is still potentially changing in compatibility-breaking ways, and should be used in production with care.
- Addon Version 1.X.X and onwards would have solidified the public API. Any notable changes that break backwards compatibility would warrant a bump in the major version (to 2.X.X and onwards).
- New features that do not break backwards compatibility would bump the minor revision number.
For example: 1.0.0 -> 1.1.0
- Bug fixes and other patches that do not change functionality would simply bump the patch number.
For example: 0.5.12 -> 0.5.13
- Version numbers could go above 9 in each category without breaking parsing (which you can't do with floats - 0.9 would be treated bigger than 0.10 and 0.11, so you'd have to do 0.9 -> 0.91).

And probably the biggest thing: Semantic versioning makes dependency management actually feasible. If your project uses Addon version 1.2.23, then the project should keep working perfectly fine with Addon version 1.X.X, as long as the exact version is above or equal to the one that was used. Construct 2's addon system will hopefully evolve to have project-specific (local) addons eventually, along with a proper addon management system, and semantic versioning would be the solid foundation to build such a system on.

Transitioning to semantic versioning should not be hard either. Existing version numbers in the format X.Y could simply be treated as 0.X.Y until the plugin authors update to actual semantic version numbers.

(As for implementing semantic version parsing in C2, for inspiration here's the semver module that npm, the Node.js package manager, uses. Also, as a sidenote, package management in Node with npm is absolutely fantastic, so following suit with what has been done there most certainly wouldn't hurt.)Daiz2013-04-15 06:55:23
B
16
S
8
G
4
Posts: 136
Reputation: 3,144

Post » Mon Apr 15, 2013 10:12 am

Makes sense (semantically) to me.
B
105
S
20
G
12
Posts: 549
Reputation: 20,320

Post » Mon Apr 15, 2013 1:17 pm

It's a good idea, but I don't think it's really necessary right now. The version field is not displayed anywhere. You can just use an incrementing number like C2 release numbers.
Scirra Founder
B
359
S
214
G
72
Posts: 22,949
Reputation: 178,544

Post » Mon Apr 15, 2013 1:28 pm

[QUOTE=Ashley] It's a good idea, but I don't think it's really necessary right now.[/QUOTE]
I'd say that's a very good reason to start supporting them now / as soon as possible. As I mentioned, the transition could be made very painless: Simply treat existing version numbers like X.Y as 0.X.Y. This way the old version numbers would basically always be treated as earlier versions in comparison to semantic version numbers. The old version numbers would be easy to support for a long time, all the while encouraging existing and new addons developers to use semantic versioning.

This would lay a solid foundation for further developments in addon management - it'd be much easier to do the "official" switch now on its own rather than doing it at the same time with some other potentially much larger changes. Not to mention that semantic versioning is simply a good development practice in general, and encouraging people to use is only going to be beneficial.Daiz2013-04-15 13:29:30
B
16
S
8
G
4
Posts: 136
Reputation: 3,144

Post » Tue Apr 16, 2013 12:03 am

@Daiz @Ashley

I agree with @Ashley,
The problem is not at version number. A updated notification tool of 3rd plugins might be more important since there already had more then 200 plugins.rexrainbow2013-04-16 00:59:01
B
97
S
22
G
177
Posts: 4,111
Reputation: 103,525

Post » Tue Apr 16, 2013 9:28 am

@rexrainbow

An update notification tool for third-party plugins is especially the kind of thing that you should have semantic versioning for. The current system "works" because you have to download and install things manually. Semantic versioning will be more and more important as installing and managing plugins becomes smoother. You don't necessarily want to always update if a new version is available - what if said new version of a plugin is a major redo of the way it works and is used? With no established versioning semantics, this could be a jump from version 1.3 to 1.4. Poor is the chap who decides to upgrade said plugin for a project that heavily relies on the way it currently works in 1.3, only to find out that most of the functionality is deprecated and he/she should redo it to be safe (since no new code with the old deprecated ACEs could be done).

With semantic versioning, this kind of jump would require bumping the major revision number, and any update tool could instantly tell that "yeah, you probably don't want to update that plugin or something's gonna break." Incidentally, this is also why project-specific plugins should really be a thing - so you could have multiple versions of plugins with no issues! Again, I point to Node.js and npm - this is practically a completely solved problem over there, and semantic versioning is a big part of it.Daiz2013-04-16 09:28:57
B
16
S
8
G
4
Posts: 136
Reputation: 3,144

Post » Tue Apr 16, 2013 9:50 am

@Daiz

Yes, the semantic versioning is a good idea, too. (Like @Ashley said)
But, the updated notification tool is not existed, every plugin need to check by manually. So that I though an updated notification tool is more important then semantic versioning. (the priority of updated notification tool is higher then semantic versioning, I thought.)

User could download all updated plugins without checking the version number, more over, the updating could do every time when opened C2 automatically to keep the plugins at the latest version (without checking the version number).
rexrainbow2013-04-16 09:55:21
B
97
S
22
G
177
Posts: 4,111
Reputation: 103,525

Post » Tue Apr 16, 2013 10:06 am

@Daiz

I though it should create another plugin if the ACE is not compatible, like the actions had been removed. -- It will cause the capx be locked. (could not open the capx file)
User need to keep the older plugin, open the capx, remove the un-existed action(or condition,expression), save it, then update the plugin to new one.

It is easy to keep compatible by setting the ACE to depressed. (without remove it)

Well, it's just another problem about maintaining plugin.rexrainbow2013-04-16 10:07:14
B
97
S
22
G
177
Posts: 4,111
Reputation: 103,525

Post » Thu Apr 18, 2013 7:23 pm

It's a good way of versioning and I'd love to get into the habit myself, but I'm too used to -

MyProject v0.01 2013_0418.capx

Old habit from many years of saving my PSDs that way.
B
15
S
5
G
7
Posts: 877
Reputation: 5,650


Return to Javascript SDK

Who is online

Users browsing this forum: No registered users and 0 guests