Configuration¶

The configuration file is required to run all changelogd commands except fo init. By default, the script looks for config file within the changelog.d directory in the current working directory. The configuration file path can be changed in one of the standard Python packages configuration files:

tox.ini or setup.cfg:

[tool:changelogd]
config=<custom-path-to>/config.yaml

pyproject.toml:

[tool.changelogd]
config = '<custom-path-to>/config.yaml'

A default configuration file generated by the changelogd init command should look like below:

context:  # All variables defined here will be passed into templates
  issues_url: http://repo/issues
message_types: # The order defined below will be preserved in the output changelog file
- name: feature
  title: Features
- name: bug
  title: Bug fixes
- name: doc
  title: Documentation changes
- name: deprecation
  title: Deprecations
- name: other
  title: Other changes
entry_fields:
- name: issue_id
  verbose_name: Issue ID
  required: false
  multiple: true
- name: message
  verbose_name: Changelog message
  required: true
output_file: ..\changelog.md
partial_release_name: unreleased
user_data:
- os_user
- git_user
- git_email

context¶

This is a place for user-defined key-value pairs that will be passed into all templates. There is no limitation on how many variables will be passed here.

message_types¶

Define supported message types. The name argument defines the type name which will be saved in the entry file name, tittle is meant to be displayed as a header in the changelog file.

The changelog entries are grouped by their message type. The order of the message types definitions within the configuration file will be preserved in the output changelog file.

If a message type will be removed from the configuration, and they’re still will be some entries that are using that type, they will not be generated into the output changelog file.

entry_fields¶

Define which fields will be asked with changelogd entry command. This is a list of objects with the following fields:

- name - the name under which the field will be available in the template. It cannot contain spaces or dashes.

- verbose_name - the name displayed when the program will ask for the field value.

- required (default: true) - the changelog entry won’t allow to leave the field blank if required=True

- multiple (default: false) - the variable can be provided as comma-separated values. This will be converted into a list of strings (even if there is no comma in it).

- default (default: empty) - define a default value. Can use computed values by specifying compute: <type>.

The defined entry_fields can be also provided as a command-line arguments, e.g. changelogd entry --message "Some message". The missing fields will be asked interactively. Use changelogd entry --help to see which fields are available.

output_file¶

Path to the output changelog file. By default, it is ../changelogd.md, which is relative to the config.yaml file.

partial_release_name¶

Name of the current, not-yet-released version when using the changelogd partial command. Default: unreleased.

user_data¶

Define fields will be captured with each entry. Available choices are:: - os_user - currently logged in system user username,

- git_user - full name of the current user from the git configuration,

- git_email - current user’s e-mail from the git configuration.

Each field’s name can be changed, by defining new name after colon, e.g.: os_user:new_name. Set the user_data value to null to avoid capturing the user data at all.

computed_values¶

Computed values is a feature, that allows to capture a dynamic value from environment. The computed_values variable is a list of objects that have to define a type value.

The allowed types are:

local_branch_name - get the name of a local branch,
remote_branch_name - get the name of a remote branch,
branch_name - get the local and remote branch name separated by - (mostly suitable for running regex over it).
last_commit_message - get the latest commit message.

Besides type, there are additional variables that can influence the output:

regex - regular expression that will be used to extract a value from the command output. The regex need to define a named group called value (e.g. (?P<value>expression)) which will be taken as a final value,
name - name of the variable in the entry file, if not provided, the type value will be taken,
default - the default value that will be used if the value (matched or returned from the dynamic command) will be empty.