version-bump

Configuration

version-bump has two modes of operation: automatic / manual. In automatic mode, version-bump will try to identify versions of all supported languages in the root of a project (wherever executed). In a manual mode, version-bump will read a configuration file to determine which modifications to make. It is expected be executed in the root of the project where the configuration file is located.

Default Settings

Language	Expected Patterns	Filename
Docker	org.opencontainers.image.version label	Dockerfile
Go	String constant named Version/version	*.go
JavaScript	JSON version field	package.json, package-lock.json

Manual

1. Create a configuration .bump file in the root of a project.

2. Add project languages and their configuration in a form of:

   [ language_name ]
   enabled = bool
   directories = [ string, string, ... ]
   exclude_files = [ string, string, ... ]
   files = [ string, string, ... ]
   regex = [string, string, ...]
   

   • [ language_name ] - one of [ 'docker', 'go', 'javascript' ]
   • enabled - default false
   • directories - path default ['.']
   • exclude_files - path default []
   • files - an array of glob values to overide the settings default declared in the langs module
   • regex - an array of regex patterns to overide the settings default declared in the langs module

3. Run version-bump in the root of a project: version-bump [major|minor|patch] [flags]

Generic Language

You can also add additional supported languages by using the [[generic]] directive.

[[generic]]
name = string
enabled = bool
directories = [ string, string, ... ]
exclude_files = [ string, string, ... ]
files = [ string, string, ... ]
regex = [string, string, ...]

Example

[docker]
enabled = true
directories = [ '.', 'tools/qa' ]

[go]
enabled = true
directories = [ 'server', 'tools/cli', 'tools/qa' ]
exclude_files = [ 'server/server_test.go', 'tools/qa/main_test.go' ]

[javascript]
enabled = true
directories = [ 'client' ]

[[generic]]
name = "markdown"
enabled = true
files = [ "*.md" ]

[[generic]]
name = "yaml"
enabled = false
directories = [ "config" ]
files = [ "*.yml" ]
regex = [ '^version: (?P<version>{{SEMVER_REGEX}})' ]

Note: the convenient {{SEMVER_REGEX}}) variable is substituted for an actual regex pattern matching a semver string.

Installation

go install github.com/joe-at-startupmedia/version-bump/v2/cmd/version-bump@latest

CLI Usage

This application increments the semantic version of a project.
It can bump semantic versions in multiple different files at once,
as well as automate prerelease versioning and promotion.

Usage:
  version-bump [major|minor|patch] [flags]

Flags:
      --alpha               alpha Prerelease
      --auto-confirm        disable confirmation prompts and automatically confirm
      --beta                beta Prerelease
      --debug               output debug information to the console
      --disable-prompts     disable passphrase and confirmation prompts. Caution: this will result in unsigned commits, tags and releases!
      --dry-run             perform a dry run without modifying any files or interacting with git
  -h, --help                help for version-bump
      --interactive         enable interactive mode
      --metadata string     provide metadata for the Prerelease
      --passphrase string   provide gpg passphrase as a flag instead of a secure prompt. Caution!
      --rc                  release candidate Prerelease
  -v, --version             version for version-bump

Version Types

Versions can be optionally specified as an argument along with prerelease flags and metadata. Must be one of the following:

• major
• minor
• patch

Bump A Major Version

➜ version-bump major

Bump A Minor Version

➜ version-bump minor

Bump A Patch Version

➜ version-bump patch

Screenshot

When incrementing a prerelease without updating the version, simply omit the version type argument.

Prerelease Automation

Types

Prereleases can be specified as a flag along with metadata. The currently supported prerelease types are the following:

• alpha
• beta
• rc

Format

Conforming to the Semver specification, Prereleases must be in the following format:

prerelease-type.prerelease-version+prerelease-metadata

Where the following criterion must be met:

• prerelease-type: Must be a string value matching one of the prerelease types
• prerelease-version: Must be an integer
• prerelease-metadata: An alphanumberic string without special characters beginning with a +

Alpha Prerelease

Must be released from an existing alpha release whose patch is the same by omitting the version type argument:

➜ version-bump --alpha

Or from a new version by specifying the version type:

➜ version-bump [major|minor|patch] --alpha

Beta Prerelease

Must be released from an existing alpha or beta release whose patch is the same by omitting the version type argument:

➜ version-bump --beta

Attempting to release an alpha release from a beta release without specifying the version type will throw an error:

➜ version-bump [major|minor|patch] --beta

Release Candidate

Similar to alpha releases and beta releases, the flags must be specified appropriately.

➜ version-bump --rc

Attempting to release an alpha release or a beta release and omitting the version type argument will produce errors:

➜ version-bump [major|minor|patch] --rc

Increment Prerelease Version

Simply specify the same prerelease type of the existing prerelease while omitting the version type argument. It will automatically increment the prerelease version.

➜ version-bump [--alpha | --beta | --rc]

Promote Prerelease

After our Prerelease has been tested and ready for rollout, you can simply provide patch as the version type argument. It will remove all of the Prerelease versioning and metadata from the version.

➜ version-bump patch

Version Inconsistencies

Before any modifications are made to the repository, if any version consistencies are detected, version-bump will prematurely exit. This frees you from the hassle of having to run git stash.

No modifications will be made with or without the auto confirmation flag specified. This screenshot demonstrates the inconsistent versioning error being triggered without auto confirmation enabled.

Auto Confirmation

By default you have to confirm each change to a pattern matched version instance. If the program prematurely exits before completion of the cormation prompts, no modification will be made to the repository. If you want to skip this bevahior, simply provide the --auto-confirm flags.

➜ version-bump [major|minor|patch] [--alpha | --beta | --rc] --auto-confirm

GPG Signing

If GPG signing is detected from the local or global git configuration, you will be prompted to enter you GPG passphrase in a secure fashion. This will allow commits and tags to verified as a result of a successful version increment. In order for GPG passphrase prompts to be enabled you must have GPG signing configured correctly.

To disable this behavior you can provide the --disable-prompts flag.

➜ version-bump [major|minor|patch] [--alpha | --beta | --rc] --disable-prompts

Interactive Mode

Another option automate releases it to use interactive mode by specifying the --interactive flag.

➜ version-bump `--interactive`

Creating A New Language

This will allow you to specify a new configuration directive in your .bump configuration. The codebase has been refactored to a point to make this process as simple as possible. In the future more refactoring can provide improvements.

See issue #2 for instructions and more specifically, this commit.