Versioning scheme

Our projects follow the Semantic Versioning 2.0.0 scheme with the addition of a leading v prefix. Each release is tagged with a vMAJOR.MINOR.PATCH tag (e.g. v1.0.0). In addition, each project contains a workflow which automatically updates matching vMAJOR.MINOR and vMAJOR tags to the same commit as that of the vMAJOR.MINOR.PATCH tag. This allows users the freedom to specify an exact version in a workflow (e.g. v1.0.0), a version with only major and minor numbers (e.g. v1.0), or a version with only a major number (e.g. v1). The latter two options would result in workflow runs automatically using the latest available version of the action with a matching major and minor version number or matching major version number respectively.

The branching/tagging model can be visualised like this:

%%{init: { 'theme': 'default' , 'themeVariables': {
    'git0': '#4585ed',
    'git1': '#edad45'
} } }%%
gitGraph
    commit
    branch feature
    commit
    commit
    commit
    checkout main
    merge feature tag: "v1.0.0"
    branch another-feature
    commit
    commit
    commit
    checkout main
    merge another-feature tag: "v1.1.0, v1.1, v1"
    checkout main

Loading

Tip

For improved security we recommend that workflow authors use a commit hash when specifying the version of an external GitHub action in a workflow (such as those provided by fish-shop) with an optional comment indicating the version tag. For example:

uses: fish-shop/install-fish-shell@ a138cde6621a975172321d698e3bb025ff2f2004 # v1.0.15
  ...

Git tags are mutable and could be manipulated by a bad actor without your knowledge (e.g. v1.0.0 today may not reference the same commit as it did at some other point in time). Commit hashes on the other hand are unique and immutable. Relying on mutable git tags introduces the potential for exfiltration of sensitive information in some circumstances, such as might be obtained from environment variables in your workflow runner.

Consider keeping your dependencies updated automatically with Dependabot version updates to make the process of using commit hashes easier.