1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
|
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.
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:
.. code-block:: rst
{% 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.
|
