Changelog template reference

For a detailed guide on how to write a template changelog refer to tera's documentation.

You can also take a look at the built-in templates in cocogitto repository.

Built-in macros

Cocogitto provides built-in Tera macros to help format changelog entries in your templates. All macros are available in a single macros.tera file located in src/conventional/changelog/template/macro/.

Available macro functions:

• simple(commit) — minimal format with short hash
• remote(commit) — format with links to commits and authors
• fullhash(commit) — format with full commit hash

Import the macros in your template with:

{% import "macros" as macros %}

Then use, for example:

{{ macros::remote(commit=commit) }}
{{ macros::simple(commit=commit) }}
{{ macros::fullhash(commit=commit) }}

Context

Release

• commits :

  • Type: Array<Commit>
  • Description: commits contained in the release
  • Nullable: false

• version :

  • Type: GitRef
  • Description: tag name or/and git oid of the current release tip
  • Nullable: false

• from

  • Type: GitRef
  • Description: tag name or/and git oid of the commit preceding the release
  • Nullable: false

• date

  • Type: Date
  • Description: date of the release
  • Nullable: false

Commit

• id:

  • Type: String, SHA-1
  • Description: commit SHA-1
  • Nullable: false

• author:

  • Type: String
  • Description: the name of the commit author on the remote platform
  • Nullable: true

• signature:

  • Type: String
  • Description: the git signature of the commit author
  • Nullable: false

• type:

  • Type: String
  • Description: the conventional commit type of the commit
  • Nullable: false

• date:

  • Type: Date
  • Description: the date of the commit
  • Nullable: false

• scope:

  • Type: String
  • Description: the scope of the commit
  • Nullable: true

• summary:

  • Type: String
  • Description: the conventional commit message summary
  • Nullable: false

• body:

  • Type: String
  • Description: the conventional commit message body
  • Nullable: true

• breaking_change:

  • Type: boolean
  • Description: is the commit marked as a breaking change
  • Nullable: false

• footer:

  • Type: Array<Footer>
  • Description: the conventional commit footers
  • Nullable: false

GitRef

• tag:

  • Type: String
  • Description: a SemVer tag name, with an optional tag_prefix. null if the version is pointing to unreleased changes.
  • Nullable: true

• id:

  • Type: Sting, SHA-1
  • Description: the id of the latest commit in the release. This can be null only when using cog bump, because it generates a changelog before creating the target version.
  • Nullable: true

Footer

• token:
  • Type: String
  • Description: the footer token
  • Nullable: false
• content:
  • Type: String
  • Description: the footer content
  • Nullable: false

Remote

• platform:
  • Type: String
  • Description: url to the configured git platform in the form https://{remote} ( see: Config -> Changelog -> Remote)
  • Nullable: true
• owner:
  • Type: String
  • Description: name of the repository owner (see: Config -> Changelog -> Owner)
  • Nullable: true
• repository_url: false
  • Type: String
  • Description: url to the repository in the form https://{remote}/{owner}/{repository}( see: Config -> Changelog -> Repository)
  • Nullable: true

Filters

In addition to the tera built-in filters, you can use the following:

• unscoped
  • Description: filter unscoped commits from releases commits. Example:
  • Example:

      {% for commit in commits | unscoped %}
          {% if commit.author %}
              {% set author = "@" ~ commit.author %}
          {% else %}
              {% set author = commit.signature %}
          {% endif %}
              - {{ commit.id }} - {{ commit.summary }} - {{ author }}
      {% endfor %}
  

  • group_by_type
    • Description: group commits by their conventional commit type and sort order
    • Example:

       {% for type_group in commits | group_by_type %}
           ### {{ type_group.0 | upper_first }}
           {% for commit in type_group.1 %}
               - {{ commit.summary }}
           {% endfor %}
       {% endfor %}
    

• upper_first
  • Description: capitalize the first letter of a string
  • Example:

     {% for commit_by_type in commits | group_by_type %}
      #### {{ commit_by_type.0 | upper_first }}
     {% endfor %}