Skip to content

Latest commit

 

History

History
105 lines (82 loc) · 4.89 KB

githubrelease.md

File metadata and controls

105 lines (82 loc) · 4.89 KB

GitHub Release Template

The GitHub Release Template renders a change log suited to be used as the description of a GitHub Release.

This template only supports including the changes of a single version, so it should be combined with the Version Range setting. Compared to the default template, the GitHub Release template omits the "Change Log" and version headings and adjusts the heading levels so the changelog can is properly rendered in the Releases view of the GitHub web interface.

Note: The GitHub Release template is independent of the GitHub integration for links. Both features can be used independently of each other.

For configuration options, see GitHubRelease Template Settings.

Customization

The "GitHub Release" template is implemented using Scriban and is split into multiple files.

The generated change log can be customized by replacing one or more of the template's files. To achieve that, specify a "Custom Directory" in the template's settings (see Custom Directory setting), e.g. in the configuration file:

{
    "changelog" : {
        "template" : {
            "gitHubRelease" : {
                "customDirectory" : "./custom_theme"
            }
        }
    }
}

ChangeLog uses a virtual file system to load the template's files.

Template Virtual Filesystem

If a "custom directory" is specified, the files in this directory are "overlayed" over the template's built-in files:

  • If a file exists in the "custom directory", it is used instead of the file at the same location in the template's default file
  • If a file only exists in the template's built-in files, the built-in file is used. Thus, you only need to place the files you wish to override in the custom directory.

To override a file, the "custom directory" must use the file & directory structure defined by the template's built-in files. The "GitHub Release" template includes the following files:

<root>
 ├─helpers
 │  ├─entry-id.scriban-txt
 │  ├─entry-title.scriban-txt
 │  └─text-element.scriban-txt
 ├─partials
 │  ├─version
 │  │  ├─details
 │  │  │  ├─entry-header.scriban-txt
 │  │  │  ├─entry.scriban-txt
 │  │  │  ├─version-details-header.scriban-txt
 │  │  │  └─version-details.scriban-txt
 │  │  ├─summary
 │  │  │  ├─breakingchanges-list-header.scriban-txt
 │  │  │  ├─breakingchanges-list.scriban-txt
 │  │  │  ├─entry-list-header.scriban-txt
 │  │  │  ├─entry-list.scriban-txt
 │  │  │  └─version-summary.scriban-txt
 │  │  ├─version-header.scriban-txt
 │  │  └─version.scriban-txt
 │  ├─changelog.scriban-txt
 │  ├─content.scriban-txt
 │  └─header.scriban-txt
 └─main.scriban-txt

Note that the "GitHub Release" template is itself a customized version of the "Default" template and not all built-in files are used by default.

Files for the template are loaded from the following locations (in order of precedence):

  1. "Custom Directory" for the "GitHub Release" template
  2. "GitHub Release" template built-in files
  3. "Default" template built-in files
  • The entry point of the template is main.scriban-txt
  • In main.scriban-txt, Scriban's include feature is used to import the other files at the appropriate locations
  • The paths of the imported files are defined in the template files. This means, that additional files that do not exist in the set of built-in files can be placed in the custom directory and then be imported from one of the overridden files. Theoretically, you can build a completely custom template by replacing main.scriban-txt with a version that only uses files from the custom directory.

Version support

  • Support for templates and the "GitHub Release" template was introduced in version 0.2.
  • The option to customize the template by overriding individual files was added in version 0.4.

See Also