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**:

.. code-block:: ini

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


**pyproject.toml**:

.. code-block:: toml

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

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

.. code-block:: yaml

   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.