Trunk-based examples

All examples use the unmodified TrunkBased preview preset:

workflow: TrunkBased/preview1

Each scenario starts independently on main with a commit tagged 1.2.0. The diagrams display asserted FullSemVer values.

Direct commits and release tags

Two ordinary commits on main produce 1.2.1 and 1.2.2. Tagging the latter v1.2.2 preserves that version; the following commit produces 1.2.3. GitVersion calculates these values; it does not create the release tags for you. Tag the commit you release, using the version you published.

sequenceDiagram
    activate main
    main->>main: commit
    main->>main: tag 1.2.0
    rect rgb(211, 211, 211)
        Note over main: 1.2.0
    end
    main->>main: commit
    rect rgb(211, 211, 211)
        Note over main: 1.2.1
    end
    main->>main: commit
    rect rgb(211, 211, 211)
        Note over main: 1.2.2
    end
    main->>main: tag v1.2.2
    rect rgb(211, 211, 211)
        Note over main: 1.2.2
    end
    main->>main: commit
    rect rgb(211, 211, 211)
        Note over main: 1.2.3
    end

Feature merge

Create feature/foo from the tagged main commit, make two commits, and merge it into main with git merge --no-ff feature/foo. The feature defaults to a Minor increment: the branch builds are 1.3.0-foo.1 and 1.3.0-foo.2. The merge produces 1.3.0 on main, and the next ordinary main commit produces 1.3.1. Delete the feature branch after merging.

sequenceDiagram
    activate main
    main->>main: commit
    main->>main: tag 1.2.0
    rect rgb(211, 211, 211)
        Note over main: 1.2.0
    end
    create participant feature_foo as feature/foo
    main->>feature_foo: branch from main
    deactivate main
    activate feature_foo
    feature_foo->>feature_foo: commit
    rect rgb(211, 211, 211)
        Note over feature_foo: 1.3.0-foo.1
    end
    feature_foo->>feature_foo: commit
    rect rgb(211, 211, 211)
        Note over feature_foo: 1.3.0-foo.2
    end
    activate main
    feature_foo->>main: merge
    deactivate feature_foo
    destroy feature_foo
    main--xfeature_foo: delete branch
    rect rgb(211, 211, 211)
        Note over main: 1.3.0
    end
    main->>main: commit
    rect rgb(211, 211, 211)
        Note over main: 1.3.1
    end

Hotfix merge

Create hotfix/fix from the tagged main commit, make two commits, and merge it with git merge --no-ff hotfix/fix. The hotfix defaults to a Patch increment: branch builds are 1.2.1-fix.1 and 1.2.1-fix.2. The merge produces 1.2.1 on main, and the next ordinary main commit produces 1.2.2. Delete the hotfix branch after merging.

sequenceDiagram
    activate main
    main->>main: commit
    main->>main: tag 1.2.0
    rect rgb(211, 211, 211)
        Note over main: 1.2.0
    end
    create participant hotfix_fix as hotfix/fix
    main->>hotfix_fix: branch from main
    deactivate main
    activate hotfix_fix
    hotfix_fix->>hotfix_fix: commit
    rect rgb(211, 211, 211)
        Note over hotfix_fix: 1.2.1-fix.1
    end
    hotfix_fix->>hotfix_fix: commit
    rect rgb(211, 211, 211)
        Note over hotfix_fix: 1.2.1-fix.2
    end
    activate main
    hotfix_fix->>main: merge
    deactivate hotfix_fix
    destroy hotfix_fix
    main--xhotfix_fix: delete branch
    rect rgb(211, 211, 211)
        Note over main: 1.2.1
    end
    main->>main: commit
    rect rgb(211, 211, 211)
        Note over main: 1.2.2
    end

Commit-message increments

On main, the following sequence illustrates the enabled commit-message rules:

Commit message FullSemVer
Fix a bug +semver: patch 1.2.1
Add an API +semver: minor 1.3.0
Break an API +semver: major 2.0.0
Ordinary commit 2.0.1

The default patterns also accept fix, feature, and breaking as aliases for patch, minor, and major. See version increments for the configurable message patterns.

sequenceDiagram
    activate main
    main->>main: commit
    main->>main: tag 1.2.0
    rect rgb(211, 211, 211)
        Note over main: 1.2.0
    end
    main->>main: Commit 'Fix a bug +semver: patch'
    rect rgb(211, 211, 211)
        Note over main: 1.2.1
    end
    main->>main: Commit 'Add an API +semver: minor'
    rect rgb(211, 211, 211)
        Note over main: 1.3.0
    end
    main->>main: Commit 'Break an API +semver: major'
    rect rgb(211, 211, 211)
        Note over main: 2.0.0
    end
    main->>main: commit
    rect rgb(211, 211, 211)
        Note over main: 2.0.1
    end

Executable source

These diagrams come from DocumentationSamplesForTrunkBased.cs, which constructs TrunkBasedConfigurationBuilder.New.Build() in each scenario and asserts every displayed version. To update them, run the GenerateMermaidSources Cake task and then ValidateMermaidDiagrams. See contributing examples.