Introduce versioning and release scheme
opatut opened this issue · 1 comments
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.
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.