docs-onboarding/versioning.md

# Versioning and Change Logs

Tl;dr:

```bash
# Base line for change log
git tag -a 2021-09-final-1 -m "Initial release as base line"
git push origin 2021-09-final-1

# Add your work
git commit -m "new: New section xyz has been added."
git commit -m "fix: Section abc has been improved for better readability."

# Add release notes to CHANGELOG.md
bash resources/scripts/release-notes.bash > CHANGELOG.md
```

## Versioning with tags

We utilize a hybrid versioning scheme, blending [Semantic Versioning](https://semver.org/) with [CalVer](https://calver.org/):

```text
YYYY-MM-[RELEASE_TYPE]-N
```

Components of the version number are as follows:

- `YYYY`, `MM`: Year and month of release.
- `RELEASE_TYPE`: Specifies the development stage:
  - `alpha`: Initial testing phase.
  - `beta`: Near-complete features, further testing.
  - `rc` (release candidate): Stability testing, bug fixes.
  - `final`: Production-ready release.
- `N`: Incremental release number for multiple releases within one month.

To add a tag to a commit you can either use the `git tag` command or the Azure DevOps UI. The following command will add a tag to the latest commit:

```bash
git tag -a 2021-09-alpha-1 -m "Initial alpha release"
git push origin 2021-09-alpha-1
```

Right now we are manually maintaining the `final` version numbers to ensure that the right commits get the right version number. This is a manual process and can be automated in the future.

## Release Notes from Git Commits

The idea is to get rather automated release notes. To have this as easy as possible, we need:

- key words for the kind of change we applied:
  - `new:` - for newly added functionality
  - `update:` - for updated functionality
  - `fix:` - for fixed functionality
  - `delete:` - for removed functionality
  - Everything else will be ignored

- A git commit example for a new feature: `git commit -m "new: added new feature"`
- A git commit example for something you don't want to show in the release notes (omit any of the keywords at the beginning): `git commit -m "updated readme"`

[resources/scripts/release-notes.bash](resources/scripts/release-notes.bash) is an example bash script to generate the release notes. You can run it with the following command:

```bash
bash resources/scripts/release-notes.bash
```

As we don't want to rely 100% on the script output and want to have the possibility to add some manual notes, we will add the release notes to the `CHANGELOG.md` file.