Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
contributing: Update VERSION file using commands (#2331)
The script provides an action as sub-command and updates the VERSION file based on the input and the current state of the VERSION file and gives an error when the operation does not make sense with the given VERSION file content. * Supports switch to release, rc, dev versions and updates of major, minor, and micro numbers. * Can increase minor version by two with --dev for odd versions. * Suggest commit message based on the current release procedure. * General instructions on using the script included separately. * Applied in the release procedure. * Add Bash eval output for convenience in the release procedure.
- Loading branch information
1 parent
ac9180e
commit b4b25cc
Showing
3 changed files
with
427 additions
and
28 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,99 @@ | ||
# Updating Version File | ||
|
||
Version file (`include/VERSION`) can be updated using the _update_version.md_ script. | ||
|
||
The script captures the logic of updating the version file incorporating | ||
the common actions and workflow checks. | ||
|
||
## Usage | ||
|
||
Use `--help` to get the information about actions available as sub-commands: | ||
|
||
```sh | ||
./utils/update_version.py --help | ||
``` | ||
|
||
Some sub-commands have short documentation on their own: | ||
|
||
```sh | ||
./utils/update_version.py minor --help | ||
``` | ||
|
||
All commands return YAML output on success and return non-zero return code on failure. | ||
|
||
## Examples | ||
|
||
### Checking Current Status | ||
|
||
The _status_ command prints content of the version file as YAML | ||
and adds today's date and constructs a version string: | ||
|
||
```sh | ||
./utils/update_version.py status | ||
``` | ||
|
||
Example output: | ||
|
||
```yaml | ||
today: 2022-04-27 | ||
year: 2022 | ||
major: 3 | ||
minor: 2 | ||
micro: 0dev | ||
version: 3.2.0dev | ||
``` | ||
|
||
Naturally, this also checks that the version if is accessible and fails otherwise. | ||
|
||
The _status_ command prints input for Bash _eval_ with `--bash`: | ||
|
||
```bash | ||
eval `./utils/update_version.py status --bash` | ||
echo $VERSION | ||
``` | ||
|
||
### Updating Minor Version | ||
|
||
Let's say we are at development-only version 3.1.dev and just created | ||
a new branch for 3.2 release, so we want to update the minor version | ||
to the next minor version: | ||
|
||
```sh | ||
./utils/update_version.py minor | ||
``` | ||
|
||
Separately, or as part of other changes, now is the time to commit, | ||
so the script suggests a commit message: | ||
|
||
```yaml | ||
message: Use the provided title as a commit message | ||
title: 'version: Start 3.2.0dev' | ||
``` | ||
|
||
### Error Handling | ||
|
||
The commands detect invalid states and report error messages. | ||
Continuing in the previous example, an attempt to increase | ||
the micro version will fail: | ||
|
||
```sh | ||
./utils/update_version.py micro | ||
``` | ||
|
||
The error message explains the reason, a micro version should be increased | ||
only after the release: | ||
|
||
```text | ||
Already dev with micro '0dev'. Release first before update. | ||
``` | ||
|
||
### Updating Development-only Version | ||
|
||
Development-only versions have odd minor version numbers and are never actually | ||
released. Given the branching model, all these versions are on the _main_ branch, | ||
so there the minor version is increased by two. This can be done by running | ||
the _minor_ command twice or by using the `minor --dev`: | ||
|
||
```sh | ||
./utils/update_version.py minor --dev | ||
``` |
Oops, something went wrong.