Quick Start

This guide assumes you have a Python project that you wish to use towncrier on, to generate its news files/changelogs. It will cover setting up your project with a basic configuration, which you can then feel free to customise.

Configuration

towncrier keeps its config in the PEP-518 pyproject.toml file.

The most basic configuration is annotated below:

[tool.towncrier]
    # The name of your Python package
    package = "myproject"
    # The path to your Python package.
    # If your package lives in 'src/myproject/', it must be 'src',
    # but if you don't keep your code in a 'src' dir, remove the
    # config option
    package_dir = "src"
    # Where you want your news files to come out. This can be .rst
    # or .md, towncrier's default template works with both.
    filename = "NEWS.rst"

By default, towncrier will look for news fragments inside your Python package, in a directory named newsfragments. With this example project, it will look in src/myproject/newsfragments/ for them.

Create this folder:

$ mkdir src/myproject/newsfragments/
# This makes sure that Git will never delete the empty folder
$ echo '!.gitignore' > src/myproject/newsfragments/.gitignore

The .gitignore will remain and keep Git from not tracking the directory.

Detecting Dates & Versions

towncrier needs to know what version your project is, and there are two ways you can give it:

  • For Python 2/3 compatible projects, a __version__ in the top level package. This can be either a string literal, a tuple, or an Incremental version.
  • Manually passing --version=<myversionhere> when interacting with towncrier.

As an example, if your package didn’t have a __version__, you could manually specify it when calling towncrier on the command line with the --version flag:

$ towncrier --version=1.2.3post4

towncrier will also include the date (in YYYY-MM-DD format) when generating news files. You can change this with the --date flag:

$ towncrier --date=2018-01-01

Creating News Fragments

towncrier news fragments are categorised according to their ‘type’. There are five default types, but you can configure them freely (see Configuration for details).

The five default types are:

  • feature: Signifying a new feature.
  • bugfix: Signifying a bug fix.
  • doc: Signifying a documentation improvement.
  • removal: Signifying a deprecation or removal of public API.
  • misc: A ticket has been closed, but it is not of interest to users.

When you create a news fragment, the filename consists of the ticket ID (or some other unique identifier) as well as the ‘type’. We can create some example news files to demonstrate:

$ echo 'Fixed a thing!' > src/myproject/newsfragments/1234.bugfix
$ echo 'Can also be `rst` as well!' > src/myproject/newsfragments/3456.doc.rst
$ echo 'The final part is ignored, so set it to whatever you want.' > src/myproject/newsfragments/8765.removal.txt
$ echo 'misc is special, and does not put the contents of the file in the newsfile.' > src/myproject/newsfragments/1.misc

We can then see our news fragments compiled by running towncrier in draft mode:

$ towncrier --draft

You should get an output similar to this:

$ towncrier --draft
Loading template...
Finding news fragments...
Rendering news fragments...
Draft only -- nothing has been written.
What is seen below is what would be written.

myproject 1.0.2 (2017-08-21)
============================


Bugfixes
--------

- Fixed a thing! (#1234)


Improved Documentation
----------------------

- Can also be `rst` as well! (#3456)


Deprecations and Removals
-------------------------

- The final part is ignored, so set it to whatever you want. (#8765)


Misc
----

- #1

Producing News Files In Production

To produce the news file for real, run:

$ towncrier

This command will remove the news files (with git rm) and append the built news to the filename specified in pyproject.toml, and then stage the news file changes (with git add). It leaves committing the changes up to the user.

Finale

You should now have everything you need to get started with towncrier! Please see Customising for some common customisation tasks, or Configuration for the full configuration specification.