Configuration Reference¶
towncrier
has many knobs and switches you can use, to customise it to your project’s needs.
The setup in the Quick Start doesn’t touch on many, but this document will detail each of these options for you!
For how to perform common customisation tasks, see Customisation.
[tool.towncrier]
¶
All configuration for towncrier
sits inside pyproject.toml
, under the tool.towncrier
namespace.
Please see the TOML GitHub repo for how to write TOML.
Top level keys¶
package
– The package name of your project. (Python projects only)package_dir
– The folder your package lives../
by default, some projects might need to usesrc
. (Python projects only)newsfile
– The filename of your news file.NEWS.rst
by default.fragment_directory
– If you are not storing your newsfragments in your Python package, or aren’t using Python, this is the path to where your newsfragments will be put.template
– Path to an alternate template for generating the newsfile, if you have one.start_line
– The magic string thattowncrier
looks for when considering where the release notes should start... towncrier release notes start
by default.title_format
– A format string for the title of your project.{name} {version} ({project_date})
by default.issue_format
– A format string for rendering the issue/ticket number in newsfiles.#{issue}
by default.underlines
– The characters used for underlining headers.["=", "-", "~"]
by default.
Custom fragment types¶
Towncrier
allows defining custom fragment types. Custom fragment types
will be used instead towncrier
default ones, they are not combined.
Users can configure each of their own custom fragment types by adding tables to
the pyproject.toml named [tool.towncrier.fragment.<a custom fragment type>]
.
These tables may include the following optional keys:
name
: The description of the fragment type, as it must be included in the news file. If omitted, it defaults to its fragment type, but capitalized.showcontent
: Whether if the fragment contents should be included in the news file. If omitted, it defaults totrue
For example, if you want your custom fragment types to be
["feat", "fix", "chore",]
and you want all
of them to use the default configuration except "chore"
you can do it as
follows:
[tool.towncrier]
[tool.towncrier.fragment.feat]
[tool.towncrier.fragment.fix]
[tool.towncrier.fragment.chore]
name = "Other Tasks"
showcontent = false
DEPRECATED: Defining custom fragment types with an array of toml tables¶
Users can create their own custom fragment types by adding an array of
tables to the pyproject.toml named [[tool.towncrier.type]]
.
If still using this way to configure custom fragment types,
please notice that fragment_types
must be empty or not provided.
Each custom type ([[tool.towncrier.type]]
) has the following
mandatory keys:
directory
: The type of the fragment.name
: The description of the fragment type, as it must be included in the news file.showcontent
: Whether if the fragment contents should be included in the news file.
For example:
[tool.towncrier]
[[tool.towncrier.type]]
directory = "deprecation"
name = "Deprecations"
showcontent = true
[[tool.towncrier.type]]
directory = "chore"
name = "Other Tasks"
showcontent = false