Hotfix Version Requirements

The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in RFC 2119.

Restrictions

  • Hotfix branches MUST NOT contain any breaking changes or new features

  • Hotfix branches SHOULD NOT contain any changes other than urgent bug fixes

  • Hotfix bug fixes MUST use the fix conventional commit tag

  • Hotfix branches MUST have an identifier unique to the version they’re based on

    This could be “customername” if and only if there is no more than a single hotfix branch for that customer on that version.

  • Hotfix branches SHOULD split off directly from (tagged) releases

  • Hotfix branches MUST NOT split off from pre-release versions

    Because hotfixes are only relevant for full releases, not pre-releases or development snapshots.

Requirements

A hotfix version:

  • MUST always compare as coming after the version it’s based on and before any next released version
  • MUST always compare as coming after any previous hotfix version, with the same identifier, it’s directly based on

In order to address these requirements, for semver 1 and 2, the following format of a hotfix version is prescribed:

Given a base version X.Y.Z that the hotfix is based on, a hotfix version is formatted as X.Y.${Z + 1}-hotfix.${ID}.${N}.

  • ID represents an alpha-numeric identifier that should be unique and is determined based on configuration.
    • ID MUST start with a letter ([a-zA-Z]) and MUST end with an alphanumeric character ([a-zA-Z0-9]) and MAY contain hyphens and periods ([-.a-zA-Z0-9])
    • In order to prevent compatibility problems ID MUST NOT have any of these forms ^(a|b|c|rc|alpha|beta|pre|preview|post|rev|r|dev)[-.]?[0-9]*$
  • N is a monotonically increasing integer

N MAY be determined by the commit distance through the first parent of the hotfix change to the base version. N MAY alternatively be the direct successor of the hotfix produced immediately before (0 for the first, 1, 2, 3, etc.). Consumers SHOULD NOT rely on the absolute value of N and SHOULD instead only use it to derive a total order for all versions that share the same identifier.

As a default, in absence of configuration, ID SHOULD be derived from the commit hash of the direct descendent of the base version. If there are multiple such direct descendants, the one reachable through the left-most (usually first) parents MUST be used. If and only if ID is constructed directly from that commit hash (derived or in full) it MUST be formatted as g${PREFIX_OF_COMMIT_HASH}.

If ID is _not_ constructed from (a prefix of) the aforementioned commit hash it MUST NOT match the regex /^g[0-9a-fA-F]+$/ to prevent ambiguity.

It SHOULD be possible to configure ID to be derived from the name of the hotfix branch. This MAY be accomplished by a configurable regex. If such a regex is used the implementation SHOULD reject duplicating of the base version in the ID field.