# 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.

By default, a message type will not be rendered if it doesn’t have any entries. To change that, set `include_empty` to `true` for a particular message type. You can then change the template, to render some message in place of entries as in the example below:

    {% for entry in group.entries %}
        {{ entry }}
    {% else %}
        {{group.empty_message }}
    {% endfor %}

Note

You will need to define `empty_message` (or similar) variable for the message type that has the `include_empty` enabled or just hardcode the empty message in the template that will be the same for all message types.

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.