Releases

Releases are deployable software iterations that can be packaged and made available to others. Releases in GitHub are based on Git Tags, which mark specific points in a repository's history.

Releases can have any format, but we follow semantic versioning, which has the format: MAJOR.MINOR.PATCH. Where MAJOR changes introduce a breaking change, MINOR introduce a new feature, and PATCH contains a fix. For more information on semantic versioning see this guide.

Creating a Release

A new release tag should be created everytime that a push is made to the main branch.

To make your first release tag, navigate to your personal learning space repository on your local machine. Within your repository, making your first tag is as simple as writing:

git tag 0.0.0

You have now created a tag in your local git repository! If you also want your tag to appear on the right panel of your repository on GitHub, as shown in the image to the right, then you will have to push your tag. To push a tag to GitHub is very similar to pushing any other change, use:

git push --tag

You have now created your first tag and pushed it to GitHub!

Automatic release tags

It is possible to automate the local creation of release tags using Commitizen. If commit messages have been written using the commitizen standard then the cz bump command is able to determine the type of semantic changes that have been made since the last tag and bump the version appropriately. The only thing you have to do is to push the tag to GitHub.

Command and output

% cz bump

bump: version 0.0.0 → 0.1.0
tag to create: 0.1.0
increment detected: MINOR

Change Logs

A change log is a type of documentation that list all of the changes that have been made during the project's lifetime. It is important to allow users to see which changes have been made to the new version of the project, in order to evaluate if it will break any software which is dependant on your project. Again, this is where semantic versioning is very useful, as it allows the user to quickly determine if updating version will cause issues.

This might sound like a laborious to do, but thankfully there are tools to automate this! Commitizen is able to create change logs for us. To create a change log with Commitizen use:

Command and output

cz changelog

or, shortened:

cz ch

This creates a file CHANGELOG.md:

% cat CHANGELOG.md
## 0.2.0 (2022-06-02)

### Feat

- **poetry**: updated toml to include poetry

## 0.1.0 (2022-05-24)

### Fix

- **python-workflow**: fix version
- **test.yml**: repo address

### Feat

- **workflow**: test workflow
- **workflow**: test workflow
- **workflows**: changed triggers for branch rules
- **branch-name**: restrictions to valid branch names
- **.gitignore**: ignore macOS .DS_Store file
- **pre-commit**: added pre-commit config

### Refactor

- **hello.py**: comments
- **hello.py**: comments

Hot tip - Creating a release tag and change log simultaneously

We don't have to perform each of these steps separately, Commitizen allows us to do both at the same time. To do so, run:

cz bump -ch

Use what you've learnt

At this point, you should have a tagged version 0.0.0 of your repository, next use what you have learnt to create a new version and change log - use both ways and make multiple new versions. But first, you need to make a change before you can bump the version.

Combining Poetry and Commitizen

Within Poetry's pyproject.toml file, a call to commitizen can be made to automatically bump the project's Poetry version when cz bump is used to create new tags.

[tool.poetry]
name = "{your-name}-learning-space"
version = "0.0.0"
description = "Safe space to learn"
authors = ["{name}"]
license = "MIT"

[tool.commitizen]
name = "cz_conventional_commits"
version = "0.0.0"
tag_format = "$version"
version_files = ["pyproject.toml:version"]