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"`.
- In general, write meaningful commit messages. Avoid generic stuff like "new version", "updated readme", "enhanced wording" etc. Try to put yourself in the shoes of someone who has to understand what you did without looking at the whole code or document.

[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.

To have the script ad hand whenever you need it, you can add the folder where it is located to your `PATH` environment variable. This is an example of the Ansible snipped for macOS based systems assuming you have git cloned this repository to your home directory under `Development` subfolder:

```yaml
- name: Add release-notes script to path
  lineinfile:
    path: "/Users/{{ macos_user }}/.zshrc"
    line: 'export PATH=$PATH:/Users/{{ macos_user }}/Development/docs-onboarding/resources/scripts'
    state: present
```

And this would be the equivalent for Windows:

```yaml
- name: Add release-notes script to path
  win_path:
    elements:
      - C:\Users\{{ windows_user }}\Development\docs-onboarding\resources\scripts
    state: present
```