65 lines
2.4 KiB
Markdown
65 lines
2.4 KiB
Markdown
# 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.
|