Vertagus

Vertagus is a tool to enable automation around maintining versions for your source code via a source control management tool like git. You can automate checks to compare the current code version string with version string(s) found on a specific branch of your repo or in repo tags, automate bumping based on semantic commit messages, and automate creating version tags in your git repo.

Features

• Semver version validation
• Semver version bump automation (semantic commit messge conventions or user configured)
• Multiple development stage configurations (e.g., dev, staging, prod)
• Git tag automation (create version tags, maintain alias tags like 'stable', 'latest')
• Runs from a config file, or entirely from CLI options with no config file at all

Installation

To install from pip:

pip install vertagus

To install from GitHub, clone and then pip install from source:

git clone https://github.com/jdraines/vertagus.git
pip install ./vertagus

Assumptions

Vertagus assumes some things about your development and versioning process:

• You are using some sort of packaging or distribution tool that contains a structured text document like yaml or toml, and you declare your package version in that document. Vertagus calls these documents "manifests".
• You are using a source control manager (scm) like git to manage your code's changes. (Only git is currently supported.)

What it does

Configuration

Vertagus lets you declare some things about how you'd like to maintain your versioning:

• Version Strategy -- there are two strategies supported, "branch", and "tag", and you declare this as part of your scm configuration. The "branch" strategy will look at a manifest file on a particular branch to determine the highest previous version. The "tag" strategy will look through tags in a repo to determine the highest previous version.
• Manifests, which are the source of truth for your versioning. (You can declare more than one if you like, but the first one will be considered the authoritative version.)
• Rules that your versioning should follow. For example, should it match a certain regex pattern? Should it always be incrementally higher than the last version? Is your version required to be in multiple manifests, and you need to know if they are out of sync with each other? For a list of rules, you can run vertagus list-rules.
• Version Aliases whose tags can move around a bit. For example, you might use major-minor-patch semantic versioning, but you'd like to maintain a major-minor alias on whatever your most recent patch version is.
• Stages of your development process that might need different rules or aliases. This might correspond to names like dev, staging, or prod, or it could be whatever else you like, depending on how you plan to use it.
• Tag Prefixes in case you're developing in a repository that holds multiple packages. Or maybe you just like prefixes.
• Version bumping handler if you'd like an automated version bumper. Available options are semantic_commit which will read commit messages since the most recent version to determine the semver bump level, or semver in which you pass the bump level as a CLI arg.

You declare these in either a vertagus.toml or vertagus.yaml file next to your package in your repository, or you pass them as CLI options and skip the file entirely. (See Using vertagus without a config file below.) Here's an example of the yaml format:

scm:
  type: git
  tag_prefix: v
  version_strategy: tag
project:
  rules:
    - not_empty
    - type: custom_regex
      config:
        pattern: '^1.+'
    - any_increment
  manifests:
    - type: setuptools_pyproject
      path: ./pyproject.toml
      name: pyproject
  bumper:
    type: semver
  stages:
    dev:
      rules:
        - regex_dev_mmp
    prod:
      aliases:
        - string:latest
        - major.minor
      rules:
        - regex_mmp

Version strategies

Vertagus uses your scm as the source of truth for previous versions, so the version strategy is declared within the scm configuration block. Two version strategies are supported, tag and branch.

In the case of using tag, running vertagus validate will look for version tags in your source control repo and will attempt to extract the highest version seen there for use in validation of the local version state.

In the case of using branch, some additional config parameters are required:

scm:
  # other scm params
  version_strategy: branch
  target_branch: main
  manifest_path: pyproject.toml  # path relative to repo root
  manifest_type: toml
  manifest_loc: ["project", "version"]

For branch, vertagus will extract the version from the manifest on the target branch to be used as the highest previous version for use in validation of the local version state.

Also note that when branch strategy is specified, the branch to be used can be overridden in the vertagus validate CLI command. (See below.) This allows for adding automated version checks against other branches in the case of a git-flow style merge pattern.

Available Rules

For a complete list of rules that can be used in the configuration, you can run vertagus list-rules to see the available rules and whether they can be used as increment or current rules.

(See the configuration docs for more on the format of this file.)

Command Line Interface

Vertagus provides two main operations in its vertagus CLI:

validate

The validate command looks like this:

vertagus validate [--stage-name STAGE_NAME --config CONFIG_FILEPATH --scm-branch SCM_BRANCH_NAME]

The validate command will check your configuration and run any rules that you have declared there. If any of the rules are being broken by the current state of the code, then it will exit with exit code 1. Otherwise, it exits without error.

create-tag

The create-tag command looks like this:

vertagus create-tag [--stage-name STAGE_NAME --config CONFIG_FILEPATH]

The create-tag command will check your configuration and create tags for the current version of your code as well as for any aliases that may be declared. These tags are created locally, but then pushed to your remote.

Additionally, Vertagus provides a number of commands for discovering the names of rules, aliases, manifets, ans scm providers:

bump

The bump command looks like this:

vertagus bump [--stage-name STAGE_NAME --config CONFIG_FILEPATH --no-write [BUMPER_KWARGS]]

The BUMPER_KWARGS should be string arguments of type key=value set apart by spaces that meet the call requirements of the bumper that has been configured.

If you have configured your vertagus config to use the semantic_commit bumper, for example:

project:
  bumper:
    type: semantic_commit

Then when you run

vertagus bump

Vertagus will look at commit messages since the last version and determine a bump level (major, minor, patch) by checking for semantic commit messages (e.g. feat: foo, BREAKING CHANGE: bar).

Or, if you prefer the semvar bumper, then the following command would update your manifest in-place locally to bump the minor version:

vertagus bump level=minor

This is because the semver bumper accepts a keyword argument level which you provide as a BUMPER_KWARG

list-rules

vertagus list-rules

list-aliases

vertagus list-aliases

list-manifests

vertagus list-manifests

list-scms

vertagus list-scms

Using vertagus without a config file

The settings that make up a single project configuration can each be passed as a CLI option, so vertagus runs in a project that has no vertagus.yaml:

vertagus validate --manifest src/pyproject.toml --rule not_empty --rule any_increment

--manifest takes either a bare path, whose manifest type is inferred from the file name, or a comma-separated list of key=value pairs using the keys path, type, loc and name:

vertagus validate --manifest 'path=package.json,type=json,loc=version' --rule regex_mmp

--rule takes either a bare rule name or a rule name followed by a colon and a JSON object of rule configuration:

vertagus validate -m pyproject.toml --rule 'custom_regex:{"pattern": "^1\\..+"}'

The rest of the configuration has an option apiece: --alias, --bumper, --root, --scm-type, --tag-prefix, --version-strategy, --target-branch and --scm-manifest. Under the branch version strategy, the SCM reads the same file as your first --manifest unless you point it elsewhere with --scm-manifest:

vertagus validate -m pyproject.toml --rule any_increment --version-strategy branch --target-branch main

These options work with validate, bump, create-tag, create-aliases, show-version and show-alias. Passed alongside --config, they override the corresponding settings in that file, which is handy in CI when one job needs a single setting changed. Passed without --config, they are the whole configuration, and no config file is read from the current directory.

A few settings stay file-only, because they describe more than one configuration at once or belong to a specific provider: stages (so --stage-name requires a file), a bumper's own options beyond its type, and the git SCM's root and remote_name.

Finally, --print-config prints the configuration a command would run with and exits, so you can turn a working command into a config file:

vertagus validate -m pyproject.toml --rule not_empty --print-config > vertagus.yaml

For the full details, see the CLI reference.

Continuous Integration

You may have noticed that the operations described above are a little odd to run just anywhere any time. Vertagus is best suited to be executed in CI automation. For example, you could configure your scm platform to run the validate command when a pull request is created as a check that must pass in order to merge. Then, you could configure your scm platform to run the create-tag command after a pull request has merged and closed.

Documentation

For more documentation, see the docs directory.