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