9 minute read

Release scope attributes

The following attributes are children of the releaseScope element:

Name Type Values
releaseScope/commits list The commits in the release scope
releaseScope/finalCommit string The last commit in the release scope
releaseScope/initialCommit string The first commit in the release scope
releaseScope/previousVersion string The previous version
releaseScope/previousVersionCommit string The previous version commit
releaseScope/primeVersion string The prime version
releaseScope/primeVersionCommit string The prime version commit
releaseScope/significantCommits list The significant commits

Commits

Name releaseScope/commits
Type list
Related configuration options  
Initialized by task infer mark

The ordered list of all commits in the release scope. The list is reverse ordered, so the newest commit appears as the first element in the list, while the oldest is the last in the list.

This value may remain undefined when inference is skipped because the user overrides the version.

Furthermore this attribute may be changed by the mark task in case a new commit is added (i.e. to include generated release artifacts).

Final commit

Name releaseScope/finalCommit
Type string
Related configuration options  
Initialized by task infer mark

The last commit in the release scope, which is to say the commit to be tagged upon release, the latest commit in the current branch (HEAD). This is the first element of the commits list.

This value may remain undefined when inference is skipped because the user overrides the version or if there is no further commits after the previous version.

Furthermore this attribute may be changed by the mark task in case a new commit is added (i.e. to include generated release artifacts).

Initial commit

Name releaseScope/initialCommit
Type string
Related configuration options releaseLenient releasePrefix scheme
Initialized by task infer mark

The commit that became right after the releaseScope/previousVersionCommit, so the first commit in the range of commits belonging to the release being prepared. This is the last element of the commits list.

This value may remain undefined when inference is skipped because the user overrides the version or if there is no further commits after the previous version.

If no releaseScope/previousVersion is detected this value will be the root commit in the Git repository.

Previous version

Name releaseScope/previousVersion
Type string
Related configuration options initialVersion releaseLenient releasePrefix releaseTypes/ID/collapseVersions releaseTypes/ID/collapsedVersionQualifier releaseTypes/ID/filterTags scheme version
Initialized by task infer

The version that was released before the one being created. This is the value of the version tag applied to the releaseScope/previousVersionCommit and is found by browsing the commit history backward (in Git’s natural order) until this tag that successfully matches the release types filter is found. Upon merge commits only the first parent is considered. The search stops at the first tag that is valid according to:

This value remains undefined when inference is skipped because the user overrides the version.

Previous version commit

Name releaseScope/previousVersionCommit
Type string
Related configuration options initialVersion releaseLenient releasePrefix releaseTypes/ID/collapseVersions releaseTypes/ID/collapsedVersionQualifier releaseTypes/ID/filterTags scheme version
Initialized by task infer

The commit that the previousVersion tag points to.

This value remains undefined when no previous version can be found in the commit history or inference is skipped because the user overrides the version.

Prime version

Name releaseScope/primeVersion
Type string
Related configuration options initialVersion releaseLenient releasePrefix releaseTypes/ID/collapseVersions releaseTypes/ID/collapsedVersionQualifier scheme version
Initialized by task infer

The version that is used as the baseline when bumping version numbers when the release type uses collapsed versioning (the pre-release versioning).

This is the first version tag that is encountered browsing the commit history backwards that only has core identifiers. It is also the value of the version tag applied to the releaseScope/primeVersionCommit. Upon merge commits only the first parent is considered. The search stops at the first tag that is valid according to:

This value remains undefined when inference is skipped because the user overrides the version. It also remains undefined when not using collapsed versioning.

Also see this F.A.Q. and this post for more on the previous and prime versions.

Prime version commit

Name releaseScope/primeVersionCommit
Type string
Related configuration options initialVersion releaseLenient releasePrefix releaseTypes/ID/collapseVersions releaseTypes/ID/collapsedVersionQualifier releaseTypes/ID/filterTags scheme version
Initialized by task infer

The commit that the primeVersion tag points to.

This value remains undefined when no previous or prime version can be found in the commit history or inference is skipped because the user overrides the version. It also remains undefined when not using collapsed versioning.

Significant commits

Name releaseScope/significantCommits
Type list
Related configuration options commitMessageConventions/ID/bumpExpressions
Initialized by task infer

The ordered list of all significant commits in the release scope, considering commits to be significant when they bring information about some version identifier to bump, according to commitMessageConventions/<ID>/bumpExpressions. The list is reverse ordered, so the newest commit appears as the first element in the list, while the oldest is the last in the list.

When the current release type uses collapsed versioning significant commits may also include commits up to the prime version commit.

When this list is empty the scope has no new commits at all or the commits that have been found do not yield to a new version.

This value may remain undefined when inference is skipped because the user overrides the version.

Commit objects

Each commit in the release scope has the following properties:

Name Type Values
sha string The SHA-1 identifier of the commit
date integer The integer representing the commit timestamp
parents list The list of SHA-1 identifiers of parent commits
authorAction object The container for the commit author fields (see below)
authorAction/identity object The container for the commit author identity fields (see below)
authorAction/identity/name string The commit author name
authorAction/identity/email string The commit author email (optional)
authorAction/timeStamp object The commit author timestamp (optional)
authorAction/timeStamp/timeStamp date The actual commit author timestamp
authorAction/timeStamp/timeZone string The commit author time zone (optional)
commitAction object The container for the committer fields (see below)
commitAction/identity object The container for the committer identity fields (see below)
commitAction/identity/name string The committer name
commitAction/identity/email string The committer email (optional)
commitAction/timeStamp object The committer timestamp (optional)
commitAction/timeStamp/timeStamp date The actual committer timestamp
commitAction/timeStamp/timeZone string The committer time zone (optional)
message object The container for the commit message (see below)
message/fullMessage string The entire commit message
message/shortMessage string The first line of the commit message
message/footers map The commit footers, each modelled as a name and value pair
tags list The list of tags applied to the commit