Introduction

This package provides a changelog generator written in typescript.

It generates changelogs in various formats with as input a clearly defined yaml file, that can be tested for conformity against a schema.

Currently the supported output changelogs are:

html
markdown
rst (restructured text)
rpm changelogs
debian changelogs

Input Format

As input to the changelog generator, a well defined yaml file is used. A json schema for this specification can be found here: Changelog Generator Schema. To find out how to use the schema as a validation in your favorite editor see editor support

The yaml changelog file must follow the following format:

Example

package:
  name: changelog-generator
  author: dotcircle
  email: 'no-reply@dotcircle.co'
  debian:
    distributions:
      - testing
      - unstable
      - stable
    metadata:
      - urgency=low

releases:
  - version: unreleased
    date: unreleased
    notes:
      - This is the unreleased version, see version 1.2.3 for all possible settings

  - version: 1.2.3
    date: '2020-01-01'
    rpm_version: 1
    notes:
      - Notes only show in the markdown generator.
      - Each list item is it's own paragraph.
    deprecated:
      - This feature is deprecated and will be removed in the next release
    removed:
      - A list of removed
      - Features
    breaking:
      - A list
      - Of breaking
      - Changes
    new:
      - |
        New features. Multiline entries are supported,
        so that more complex formatting is possible
        and sub-lists can be included
        - item 1
        - item 2
    changed:
      - Changed items
    fixed:
      - Bug fixes
    downloads:
      - name: schema version 1.2.3
        url: https://dotcircle.dotpages.co/changelog_generator/schema.json

  - version: 1.2.2
    date: '2010-01-01'
    changed:
      - update the documentation for the new year

  - version: 1.2.1
    date: '2019-12-31'
    changed:
      - There may be multiple worlds - Hello Worlds

  - version: 1.2.0
    date: '2019-01-01'
    new:
      - Hello World

Global package options

package Object : Global package options.

package.name String : The package name.

package.author String : The packaging author.

package.email String : The packaging author’s email address.

package.debian Object : Debian specific options.

package.debian.distributions List[String] : List of debian release versions
It is used for the ‘Distribution’ field in the .changes file.
Defaults to [‘unstable’]

package.debian.metadata List[String] : List of debian metadata options.
The only supported keywords debian supports are ‘urgency’ and ‘binary-only’
The default is [‘urgency=low’]

Releases list

releases List[Release] : A list of releases. The version and date are required, if set to unreleased they will be omitted from the output.
This so you can keep you changelog entries with your commits, and change the version and date once you tag the release version.

releases[n].version String : Semantic version number (e.g.: 10.12.3), or ‘unreleased’.

releases[n].date String : ISO date “YYYY-MM-DD”, or ‘unreleased’.

releases[n].notes List[String] : Array of release notes, each array item will be a note paragraph in the markdown generator.

releases[n].downloads List[Download] : Array of downloads, each array item will be an entry in the release notes.
Currently only included in the markdown output.

releases[n].downloads.name String : Name of the download

releases[n].downloads.url String : Url of the download

releases[n].breaking List[String] : Array of release notes, each array item will be an entry in the release notes.
Used for breaking changes.

releases[n].new List[String] : Array of release notes, each array item will be an entry in the release notes.
Used for new features.

releases[n].changed List[String] : Array of release notes, each array item will be an entry in the release notes.
Used for changes that effect the user.

releases[n].fixed List[String] : Array of release notes, each array item will be an entry in the release notes.
Used for Fixed bugs.

releases[n].removed List[String] : Array of release notes, each array item will be an entry in the release notes.
Used for removed features.

releases[n].deprecated List[String] : Array of release notes, each array item will be an entry in the release notes.
Used for deprecated features.

Output Formats

Markdown

With the -g markdown generator option, a markdown changelog is generated.

The example above will render the following markdown:

Command

changelog-generator -g markdown changelog.yml

Output

## 1.2.3

Released: 2020-01-01

Notes only show in the markdown generator.

Each list item is it's own paragraph.

### Downloads

- [schema version 1.2.3](https://dotcircle.dotpages.co/changelog_generator/schema.json)

### Breaking

- A list
- Of breaking
- Changes

### New

- New features. Multiline entries are supported,
  so that more complex formatting is possible
  and sub-lists can be included
  - item 1
  - item 2

### Changed

- Changed items

### Fixed

- Bug fixes

### Removed

- A list of removed
- Features

### Deprecated

- This feature is deprecated and will be removed in the next release

## 1.2.2

Released: 2010-01-01

### Changed

- update the documentation for the new year

## 1.2.1

Released: 2019-12-31

### Changed

- There may be multiple worlds - Hello Worlds

## 1.2.0

Released: 2019-01-01

### New

- Hello World

Note that this doesn’t include a heading 1 or an introduction of sorts. To accomplish this, you can use the >> operand to append the generated data to a template file containing the header and introduction.

RPM Changelog

With the -g rpm generator option, a rpm compatible changelog is generated which can be included in a rpm spec file. The generated output is compatible with the rpm spec file format and should pass the rpmlint checks.

The example above will render the following changelog:

Command

changelog-generator -g rpm changelog.yml

Output

* Wed Jan 01 2020 dotcircle <no-reply@dotcircle.co> - 1.2.3-1
- breaking: A list
- breaking: Of breaking
- breaking: Changes
- new: New features. Multiline entries are supported,
  so that more complex formatting is possible
  and sub-lists can be included
  - item 1
  - item 2
- changed: Changed items
- fixed: Bug fixes
- removed: A list of removed
- removed: Features
- deprecated: This feature is deprecated and will be removed in the next release

* Fri Jan 01 2010 dotcircle <no-reply@dotcircle.co> - 1.2.2
- changed: update the documentation for the new year

* Tue Dec 31 2019 dotcircle <no-reply@dotcircle.co> - 1.2.1
- changed: There may be multiple worlds - Hello Worlds

* Tue Jan 01 2019 dotcircle <no-reply@dotcircle.co> - 1.2.0
- new: Hello World

Debian Changelog

With the -g debian generator option, a debian .deb package compatible changelog is generator which can be used to generate debian system packages. The generated output is compatible with the debian changelog format and should pass the lintian checks.

Some additional options can be set in the global package settings to customize the output:

package:
  debian:
    distributions:
      - testing
    metadata:
      - urgency=low

See the global package options for an explanation on these settings.

The example above will render the following changelog:

Command

changelog-generator -g debian changelog.yml

Output

changelog-generator (1.2.3) testing unstable stable; urgency=low

  * breaking: A list
  * breaking: Of breaking
  * breaking: Changes
  * new: New features. Multiline entries are supported,
    so that more complex formatting is possible
    and sub-lists can be included
    - item 1
    - item 2
  * changed: Changed items
  * fixed: Bug fixes
  * removed: A list of removed
  * removed: Features
  * deprecated: This feature is deprecated and will be removed in the next release

 -- dotcircle <no-reply@dotcircle.co>  Wed, 01 Jan 2020 00:00:00 +0000

changelog-generator (1.2.2) testing unstable stable; urgency=low

  * changed: update the documentation for the new year

 -- dotcircle <no-reply@dotcircle.co>  Fri, 01 Jan 2010 00:00:00 +0000

changelog-generator (1.2.1) testing unstable stable; urgency=low

  * changed: There may be multiple worlds - Hello Worlds

 -- dotcircle <no-reply@dotcircle.co>  Tue, 31 Dec 2019 00:00:00 +0000

changelog-generator (1.2.0) testing unstable stable; urgency=low

  * new: Hello World

 -- dotcircle <no-reply@dotcircle.co>  Tue, 01 Jan 2019 00:00:00 +0000

Editor Support

A lot of editors will validate a yaml file against a schema, if you ask it nicely.

JetBrains

For the JetBrains IDE’s you can find this setting in Settings / Preferences | Languages & Frameworks | Schemas and DTDs | JSON Schema Mappings where you can add a new mapping. The Schema file or URL should point to https://dotcircle.dotpages.co/changelog-generator/schema.json . The Schema version is 7. And then you can add a list of files / regex expressions for files that should be validated against this schema.

Visual Studio Code

Registering a schema in Visual Studio Code can be done in the settings page. As we are validating a yaml file, make sure you have the YAML extension installed. Then go to File | Preferences | Settings (or use the command palette) to open the settings page and search for yaml.

Search for ‘yaml schemas’ en click the ‘Edit in settings.json’ option for the setting ‘Yaml: Schemas’

add the following to the settings.json:

{
  "yaml.schemas": {
    "https://dotcircle.dotpages.co/changelog_generator/schema.json": "CHANGELOG.yml"
  }
}