Create Changelog

This action creates an initial Changelog from the commit history.

This is usually the included in your workflow after building and testing your library with CMake Workflow in another job with the complete matrix.

The commits considered go from the latest commit up to a commit containing a version commit pattern specified by version-pattern.

The result can be used as the initial body for an automated release, a CHANGELOG.md file, or a job summary.

Each commit is parsed as a loose variant of a conventional commit in the following format:

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

  • The body and footer are always ignored.

  • If no type is indicated, the description goes to an initial "other" category in the message.

  • If no scope is indicated, the description goes to an initial "general" scope in the type messages.

  • Breaking changes are indicated.

This action uses the local commit history to generate the notes. Ensure the fetch-depth option is set when cloning your repository in CI. If this option is unset, the checkout action will perform a shallow clone and the Changelog will only include the latest commit.

- uses: actions/checkout@v3
  with:
    fetch-depth: 100

This parameter can also be used as a limit on the number of commits the action should consider.

Example

steps:
- name: Changelog
  uses: alandefreitas/cpp-actions/create-changelog@v1.8.4
  with:
    output-path: CHANGELOG.md
    thank-non-regular: ${{ startsWith(github.ref, 'refs/tags/') }}
    github-token: ${{ secrets.GITHUB_TOKEN }}
    link-commits: ${{ github.ref_name == 'develop' }}

Input Parameters

Parameter

Description

Default

source-dir

The source directory from whose commits will be analyzed.

.

version-pattern

A regex pattern used to identify if a commit is a version delimiter.

When a commit has a message that matches this pattern, the list of commits considered in the notes is complete.

For instance, assuming the pattern '(Bump|Set)\s+version', when we find a commit subject such as 'Bump version to 1.0.0', the list of commits considered in the notes is complete.

This constraint does not apply to the current and latest commit.

(Bump|Set)\s+version

tag-pattern

A regex pattern used to identify if a commit is a tagged delimiter.

When a commit has the same hash has the commit associated with a tag whose name matches this pattern, the list of commits considered in the notes is complete.

For instance, assuming the pattern 'v.\..\..*', when we find a commit with the same hash as the commit associated with the tag 'v1.0.0', the list of commits considered in the notes is complete.

This tag is then associated as the parent version of the current release, and this information is included at the end of the changelog.

This constraint does not apply to the current and latest commit.

v.\..\..*

output-path

The path where the changelog will be stored.

Relative paths are resolved from the source directory.

CHANGELOG.md

limit

The limit on the number of commits considered in the Changelog.

If the limit is set to 0 or undefined, all commits are considered.

0

thank-non-regular

Thank non-regular contributors.

The action will attempt to identify non-regular contributors by analyzing the commit history and the GitHub token provided.

Non-regular contributors are contributors that do not have a are not part of the repository’s collaborators and have a small number of commits.

The changelog will include a thank you message to these contributors, including a tag to their GitHub profile.

When the Changelog is used in a release, this tag will usually be used by GitHub to notify these contributors of the new release with their contribution and the thank you message.

true

check-unconventional

Check for commits that do not follow the conventional commit format.

If one of the new commits in a PR does not follow the conventional commit format, the action will create a warning so that the user can fix the commit message.

This helps ensure all commit messages can be used in the changelog so that it’s consistent and that the release notes are clear and concise.

true

link-commits

Link commit ids in the changelog to the repository commit.

For instance, if the changelog includes a commit id such as '471aec5', instead of including "#471aec5" next to the commit message, it will include the full version with the link:

#471aec5

This is usually unnecessary because GitHub flavored markdown automatically links commits id in text to the commits in the same repository. Thus, including explicit links would often make the output more verbose and remove any extra GitHub functionality, such as pop ups associated with these ids.

However, when the outputs is only going to be used as an action summary or in any other context outside GitHub, these automatic links do not exist and it’s often a good idea to explicitly include them to allow the reader to navigate to these repository commits.

false

github-token

Github token to identify information about the project.

This is currently used to:

- Fetch the commit history to compare with the proposed changes and create a full changelog including the changes proposed in a PR and the changes that are already in the main branch. - Fetch the list of collaborators to identify non-regular contributors.

The reason we need to fetch the commit history is because the checkout action only fetches the latest commit so the information about existing commits is not readily available to the workflow.

The value for this token is usually set as the value of secrets.GITHUB_TOKEN.

Although the action does not require this token to work, it will be limited in the number of requests it can make to the GitHub API and might be forced to work with limited information.

update-summary

When set to true, this action will update the workflow summary with the current changelog.

true

trace-commands

Trace commands executed by the workflow.

false