Proposal for creating an OpenPASS project versioning system

Hi all,

Here is a collection of the information of the versioning from the various issues and merge requests.

Versioning

From issues/43:

It is proposed to use the industry-standard Semantic Versioning from semver.org. This is summarized as:

Given a version number MAJOR.MINOR.PATCH, increment the:

1. MAJOR version when you make incompatible API changes
2. MINOR version when you add functionality in a backward compatible manner
3. PATCH version when you make backward compatible bug fixes

Additional labels for pre-release and build metadata are available as extensions to the MAJOR.MINOR.PATCH format.

Tags should be the semantic version, prefixed with "v", see https://github.com/cpm-cmake/CPM.cmake/wiki/Preparing-projects-for-CPM.cmake, and as an example see https://github.com/gabime/spdlog/tags.

Changelogs

From issues/43:

Ideally, the changelog would be automatically generated from the commit messages. These commits should be squashed. This can be done with the specification from Conventional Commits, which works well with Semantic Versioning. As a summary from the website:

The commit message should be structured as follows:

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

So, an example message could be:

feat: allow provided config object to extend other configs

BREAKING CHANGE: `extends` key in config file is now used for extending other config files

The ways to indication version changes are:

• As a type, fix corresponds to an increment in the PATCH version in Semantic Versioning.
• As a type, feat corresponds to an increment in the MINOR version.
• BREAKING CHANGE in the commit body or a ! after the type/scope indicates an increment in the MAJOR version.

More details are on the Conventional Commits website.

From issues/33:

Mocks and tests for the whole API would need to be implemented to detect incompatable API changes for incrementing the MAJOR version.

Benefits:

• Easy way of detecting major version changes, meaning API breaks. Automatic checking with CI.
• Consumers can use the mock code to implement the API.

Example implementation of the mock code has been done in merge_requests/80.

• The mock classes are a replacement of test_utils.h, which is split into multiple files, with one mock per class. E.g., MockEnvironment and EnvironmentTest for IEnvironment.
• Currently contains mocks for IIdentifiable, IEnvironment, ILaneLocationQueryService, and IEntity.
• Tested on Mercedes-Benz use cases.

Release checklist

There should be a checklist for creating each release. As an example, this could be:

• Create release notes from commits
• Update the README or documentation to include information about each version, including release notes, known issues, and upgrade instructions.
• Use Git tags and releases to mark specific versions in the repository, making it easier to download a release
• Etc.

Remaining work for the first release

• Create API Mocks for each class.
• Setup CI so that changelogs can be automatically created and major version changes can be detected.
• Think about how to enforce commit messages
• Set up squashing merge commits for every merge request
• Need a well formatted template for merge commit messages

Anything else?