Introduce versioning and release scheme

[opatut]

We should start versioning this, to indicate possible breaking changes, and make sure we can communicate about it. I suggest a general version for both frontend and API. We should start at 0.1.0 and follow semver. I think we're still in initial development phase, no stable release 1.0.0 yet.

[opatut]

We're following semver 2.0.0, and there is a script to tag a new release (e.g. ./tag-release 1.2.3).

Public interface

The public interface considered for breaking changes is:

• The HTTP API, including the tile schema
• The shape of the imported data (OSM and OBS data)
• The shape of exported data (there is no export yet)
• The configuration files.
• The database schema.

Rationale

The reasoning behind this is to make it easy for platform maintainers to check whether their upgrade needs additional work. This includes

• checking for compatiblity with clients (such as the OBS device itself)
• rerunning certain import or export routines

The public interface is also rather large (including the database schema, for example), as this makes it easier to build and maintain third-party integrations, which we want to have lots of.

There is no problem with huge version numbers. Let's get bumping!

Examples for non-breaking changes

• additional routes
• additional properties or layers in the tile schema
• introducing a new export format or adding data to it
• columns not imported anymore from OSM, but still present in the database
• adding a new flag optional to the config file
• not using a flag from the config file anymore
• adding an optional column to the database
• adding a new table in the database

Examples for breaking changes

• non-backwards-compatible changes to the shape of an API route
• removal of an API route
• removing or renaming layers or properties in the tile shcema
• removing an export format or changing it in a breaking way
• importing more data from OSM or importing it in a different way that cannot be considered an improvement, but requires a reimport to still produce the same correctness of result as with the old code
• adding a required config flag
• changing the interpretation of a config flag that requires manual intervention and possible reconfiguration
• breaking change of a column in the database

Bug fixes and features

A bug fix that does not change the public interface is usually released as a patch release (e.g. 0.3.2 -> 0.3.3).

A new feature that does not cause a breaking change can be released in a minor version (e.g. 1.3.x -> 1.4.0), if it adds to the public interface. If it does not add to it but only improves something internally (such as a change to the frontend), a patch release is acceptable. During initial development (0.x versions), a patch release is used instead of a minor release in any case that is not breaking public interface.