JOSM versioning

[michael2402]

Currently, JOSM is versioned by it's SVN revision.

In the future, we want to version JOSM without relying on the JOSM version. For this, there will be two versioning schemes:

For tested versions, there will be a version of:
<year>.<month>

If we do tested releases for quickfixes (multiple tested per month), we use
<year>.<month>.1, <year>.<month>.2, ...

For latest version, we use:
<year>.<month>.<last tested minor + 1>-SNAPSHOT (e.g. 18.11.1-SNAPSHOT) to describe the current latest snapshot for the given year, month and quickfix.
When publishing snapshots, the string SNAPSHOT is replaced by a unique identifier (e.g.: 18.11.1-20181118.142301-42).

We will have a build task to do the next development iteration (tag + update version)

For @since tags, we will keep them as @since xxx in source and run the replacement as soon as we do a release and then tag them with the official release version. We don't know the exact snapshot version when adding the @since tags, but since we often use branches there is no way of determining them.

Plugins can use the SNAPSHOT version to specify that they rely on an experimental version.

[simon04]

Replying to michael2402:

For tested versions, there will be a version of:
<year>.<month>.0

If we do tested releases for quickfixes (multiple tested per month), we use
<year>.<month>.1, <year>.<month>.2, ...

Remark: Ubuntu and the ​Linux kernel omit the .0 and start counting patch releases with .1.

[Don-vip]

Hotfixes are quite rare. We must obviously keep this possibility but I agree with can usually skip the .0.

I'm not a fan about keeping @since xxx and replace it by the "human version" only when releasing a tested version. In JOSM development model, "latest" version is a functional version as well, "tested" versions are only latest versions we all agree are in good shape enough to be used broadly.

I see two usages of the @since tag:

• for plugin maintainers, to see what JOSM minimum version is required
• for JOSM developers to quickly find the commit that introduced tihs public API two years ago

The second one is not so crucial. We can use svn/git blame to retrieve this information.

As we will need the timestamp information anyway, could we keep @since xxx in the commits and have a git hook replacing xxx by a timestamp when this commit is merged on JOSM master branch? Feasible?

[michael2402]

Replying to Don-vip:

Hotfixes are quite rare. We must obviously keep this possibility but I agree with can usually skip the .0.

Ok, that's fine then.

As we will need the timestamp information anyway, could we keep @since xxx in the commits and have a git hook replacing xxx by a timestamp when this commit is merged on JOSM master branch? Feasible?

So basically we would not add any version information but in the future, any @since tag simply defines the time at which that feature was merged into master?

The problem with git commit hooks is that they run on the client. They do not run at the server, so the time inserted would be the time that developer committed to his local store and not to the upstream repository. Basically, this is a good thing since it allows us to have mirrors of our main repository.

What might be able to do is use the post-receive hook to create a new automated commit (by a bot) as soon as a feature is merged into master that then updates the since tags.

[floscher]

I wouldn't put SNAPSHOT and the actual date into the version. Since SNAPSHOT is at least in Maven a special string, we should treat it similar in our versioning system, that means:

• the latest snapshot version is always referred to as 18.11.1-SNAPSHOT (which version is actually used changes over time)
• each snapshot is actually published with a version number like this: 18.11.1-20181118.142301-42 (the 42nd snapshot, released on November 18th 2018 at 14:23:01)

That's also how the snapshots in our Nexus repository are currently versioned.

[michael2402]

Replying to floscher:

• each snapshot is actually published with a version number like this: 18.11.1-20181118.142301-42 (the 42nd snapshot, released on November 18th 2018 at 14:23:01)

Good point and good idea.

[stoecker]

As designed this version scheme is broken:

• A tested release has a smaller version number than the earlier snapshots.
• Don't include non numbers, slashes or anything alike in the version number, that makes packaging work a hell.

Apply to following rules used by all sane projects:

• A version number should only consist of numbers and dots.
• Numbers should be incremental.

A different version number for tested and latest requires a rebuild to get a tested version, which break the workflow of current build process.

[floscher]

The versioning scheme proposed here is pretty similar to ​semantic versioning used by many projects (including some sane projects).

A semantic version number consists of (up to) three numbers separated by dots. For pre-releases it is common to append a dash and an identifier. That pre-release version is then by definition lower than the version without the appended stuff:

1.0.0-beta < 1.0.0 < 1.0.1-beta < 1.0.1

Yes, we would need to change how we compare version numbers (string comparison won't cut it since e.g. 19.2 < 19.2.3 < 19.2.11 < 19.10).
Does a dash really cause problems with packaging? The versioning schema proposed here only uses (incrementing) numbers and dots, and pre-releases contain an additional dash.

The identifier doesn't have to be as long as I proposed above. I just took inspiration from the version numbers currently used in https://josm.openstreetmap.de/nexus/content/repositories/snapshots/org/openstreetmap/josm/josm/SNAPSHOT/

[stoecker]

For pre-releases it is common to append a dash and an identifier.

There are special workarounds in packaging systems for the common "rc", "alpha", "beta" strings. You propose to add numeric values, where no workarounds exist.

Does a dash really cause problems with packaging?

Yes. It does. It is a constant issue to work around all these "creative" ideas some projects have. Especially when they change.

Three numbers should really be enough to express a version or an ISO date (20180911). Keep in mind that users don't want to study our version method, they want to use the software and it should be obvious what's the newer one.

Complex methods aren't obvious and not needed.

[stoecker]

If been thinking about the suggested naming method and still fail to see the advantages of the additional complexity.

JOSMs simple system works for many years now and users have accepted it. As the SVN revision needs to be replace I think we all agree we need a date base approach instead.

So lets choose something like 2.0.1809240 (instead of 1.5.rev we have now) or 2.01809240 or 201809240 or only 1809240 (or even 2018.09.24 and 2018.09.24.1 for hotfixes if its too complicated to understand a date without dot) and keep the current development and build model except that at build time the release is tagged with the used version.

Why do we need to introduce all the other complexity?

What problems does this solve?

Advantage of this approach is that all inside and outside tools don't see any real change. Only the 5 digit SVN revision gets a bit larger suddenly.

[michael2402]

As long as we tag them on the central server, 201809240 would be a good version number.

I would even be fine with a 201809xx version assuming we do no more than 99 commits per release cycle (~ 1 month). This would allow us to always tag the xxxxxx00 versions as stable. (not as a requirement, but rather a convention) and still have relatively short version names.

I don't think that the length of the version should change. NPM is a relatively new package manager, it has a reason that they decided on fixed-length 3 component version strings (xx.xx.xx) and don't allow anything else.

EDIT: Important to note, that a version would then be determined by the time at which the corresponding commit reaches the master on our build server (for @since tags).

EDIT2: Nice side effect of using the day as @stoecker proposed is, that we can always add the date of the merge to master in our @since tags and will be pretty close to the acutal since (plugin versions don't have to be an exact match, so if you see a method that got added on 2018-10-25, set your dependency to 201810270 and you are safe)

[stoecker]

As long as we tag them on the central server, 201809240 would be a good version number.

Tagging and nightly build should be one step. A successful build should create the tag.

I would even be fine with a 201809xx version assuming we do no more than 99 commits per release cycle (~ 1 month). This would allow us to always tag the xxxxxx00 versions as stable. (not as a requirement, but rather a convention) and still have relatively short version names.

I would agree that we have not more than 9 hot-fixes a day. I would not agree that we have only 99 commits per month, especially not with git. 99 builds per months are reasonable, but loosing the day for saving one digit seems not worth the less-obvious naming.

I don't think that the length of the version should change. NPM is a relatively new package manager, it has a reason that they decided on fixed-length 3 component version strings (xx.xx.xx) and don't allow anything else.

That statement is unclear. You mean using 2.0.date with fixed-length 3? Only a few people know that josm is using 1.5.rev and not rev only. E.g. debian never catched that and uses 0.0.rev for their packages.

[Don-vip]

Replying to michael2402:

I would even be fine with a 201809xx version assuming we do no more than 99 commits per release cycle (~ 1 month).

Most releases in the past few years have more than 99 commits between them, see DevelopersGuide/Schedule.

I also like a date-based version. I just think we need to keep the possibility to release more than 1 hotfix the same day (I think it already happened in the past).

[michael2402]

Replying to stoecker:

I don't think that the length of the version should change. NPM is a relatively new package manager, it has a reason that they decided on fixed-length 3 component version strings (xx.xx.xx) and don't allow anything else.

That statement is unclear. You mean using 2.0.date with fixed-length 3? Only a few people know that josm is using 1.5.rev and not rev only. E.g. debian never catched that and uses 0.0.rev for their packages.

This was just about the 18.10 and 18.10.1 suggestion.

We can have only one integer/long as version. But I would advice against skipping the last version numbers if they are 0.

Btw, the reason why I came up with 18.10 is because that is what we currently reference the versions in Trac.

So having:

18.10.000
18.10.010
18.10.020
...
18.11.000

Would also be an option, although it is pretty uncommon to add the additional 0 and write a date in this format.

So currently my favorite would be the 201810ddx format. Simple to check against, easy to sort, easy to understand (easier than the 18.xx format) and easy to implement. And a valid git tag.