docs: extra info about creating version releases

docs/dev-guide/version-control.md

@@ -32,42 +32,81 @@
 A [specification](https://www.conventionalcommits.org/en/v1.0.0/)
 for adding human and machine readable meaning to commit messages.
 
-Format: `<type>[optional scope]: <description>`
-
-Example: `feat: allow provided config object to extend other configs`
-
 A 'new' standard for commit messages.
 
-Allows for easy semantic versioning, x.x.x, as the type of increment can be
-automatically determined based on the commit types.
+**Format**: `<type>[optional scope]: <description>`
 
-## Tools
+Example `feat: allow provided config object to extend other configs`
+Example `fix: fixed the bug in issue #123`
 
-Some tools can make your life easier when working with conventional
-commits and SemVer.
+**Advantage**: Automated SemVer version management (major.minor.patch),
+and automated changelogs.
 
-### Commitizen
+## Tool: Commitizen
 
-- Versions are managed by Commitizen from the `pyproject.toml` file in a repo.
+- [Commitizen](https://commitizen-tools.github.io/commitizen) is a
+  Python tool to help with creating **conventional commits** and
+  automating version control.
+
+- Versions are managed by Commitizen from the `pyproject.toml` file in a
+  repo.
 
 - Versions are determined by conventional commit messages:
   - `fix: xxx` denotes a patch, `feat: xxx` denotes a minor increment.
-  - Breaking changes are applied every year to increment the `YYYY` in place
-    of `MAJOR`.
+  - Breaking changes are applied every year to increment the `YYYY` in
+    place of `MAJOR`.
+
+### Install
+
+`pip install commitizen`
+
+### Commiting Code
+
+- Instead of `git commit` use `cz commit` and follow the prompts.
+- You can select the type of commit, plus additional metadata.
+
+### Bumping a Version
+
+- When you decide it is time to create a new version:
+
+1. Create a new branch
+
+   `git checkout -b bump/new_release`
+
+2. Bump the version and push
+
+   ```bash
+   pip install commitizen # (if not installed)
+
+   cz bump --check-consistency --changelog
+
+   git push
+   git push --tag
+   ```
+
+This will:
 
-#### Bumping Versions
+- Update the SemVer version number in locations specific in `pyproject.toml`,
+  throughout the codebase.
+  - If a `feat` commit is included, the version is bumped by a minor
+    increment (0.x.0), if only `fix` is included a patch will be used
+    (0.0.x).
+- Automatically update CHANGELOG.md with all changes since the last version.
+- Create a tag matching the version number.
 
-Install commitizen:
+> Note: in a repo where you have direct push access, you would simply
+> update on main and push. As we are using Git-Flow, a PR is necessary.
 
-```bash
-pip install commitizen
-```
+## Creating Releases
 
-Bump the version:
+1. Update the version throughout the code ([Bumping a Version](#bumping-a-version)).
+2. Go to the Releases page of your repo
+   (<https://github.com/ORG/REPO/releases>).
+3. Click `Draft a new release`.
+4. Click `Choose a tag`, then input the current version number and press
+   enter (this will automatically create a matching tag for your release).
+5. Set the `Release title` to v`x.x.x`, replacing with your version number.
+6. Add a description if possible, then release.
 
-```bash
-# cd to the directory containing the pyproject.toml
-cz bump --check-consistency --changelog
-git push
-git push --tag
-```
+This should trigger the PyPi publishing workflow (for HOT repos), and
+your version will be available on [PyPi.org](pypi.org).