Skip to main content

Hear ye, hear ye, says the towncrier

https://travis-ci.org/hawkowl/towncrier.svg?branch=master https://codecov.io/github/hawkowl/towncrier/coverage.svg?branch=master

towncrier is a utility to produce useful, summarised news files for your project. Rather than reading the Git history as some newer tools to produce it, or having one single file which developers all write to, towncrier reads “news fragments” which contain information useful to end users.

Philosophy

towncrier delivers the news which is convenient to those that hear it, not those that write it.

That is, by duplicating what has changed from the “developer log” (which may contain complex information about the original issue, how it was fixed, who authored the fix, and who reviewed the fix) into a “news fragment” (a small file containing just enough information to be useful to end users), towncrier can produce a digest of the changes which is valuable to those who may wish to use the software. These fragments are also commonly called “topfiles” or “newsfiles” in Twisted parlance.

towncrier works best in a development system where all merges involve closing a ticket.

Quick Start

Install from PyPI:

python3 -m pip install towncrier
# OR:
python2 -m pip install towncrier

In your project root, add a pyproject.toml file, with the contents:

[tool.towncrier]
    package = "mypackage"
    package_dir = "src"
    filename = "NEWS.rst"

Then put news fragments (see “News Fragments” below) into a “newsfragments” directory under your package (so, if your project is named “myproject”, and it’s kept under src, your newsfragments dir would be src/myproject/newsfragments/).

To prevent git from removing the newsfragments directory, make a .gitignore file in it with:

!.gitignore

This will keep the folder around, but otherwise “empty”.

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.

To produce a draft of the news file, run:

towncrier --draft

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 towncrier.ini, and then stage the news file changes (with git add). It leaves committing the changes up to the user.

If you wish to have content at the top of the news file (for example, to say where you can find the tickets), put your text above a rST comment that says:

.. towncrier release notes start

towncrier will then put the version notes after this comment, and leave your existing content that was above it where it is.

News Fragments

towncrier has a few standard types of news fragments, signified by the file extension. These 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.

The start of the filename is the ticket number, and the content is what will end up in the news file. For example, if ticket #850 is about adding a new widget, the filename would be myproject/newsfragments/850.feature and the content would be myproject.widget has been added.

Metadata

Release files for towncrier 17.8.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for towncrier 17.8.0
File Size Uploaded Provenance Actions
towncrier-17.8.0.tar.gz 17.2 kB Without provenance Details for towncrier-17.8.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for towncrier 17.8.0
File Interpreter ABI Platform Actions
towncrier-17.8.0-py2.py3-none-any.whl Python 2, Python 3 none any Details for towncrier-17.8.0-py2.py3-none-any.whl

Total release size: 35.9 kB

Release files / towncrier-17.8.0.tar.gz

Download URL towncrier-17.8.0.tar.gz
Size 17.2 kB
Tags Source
SHA-256 checksum
How to use checksums
8c0e5949851a9771a50d637b708322d73a4d4090fa354e5cb24a4f7464e81d47
BLAKE2b-256 checksum
How to use checksums
075466d0de4311ead3c5514bf9dafd25cb17816292532d4f486036a807f9c0c8
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No

Release files / towncrier-17.8.0-py2.py3-none-any.whl

Download URL towncrier-17.8.0-py2.py3-none-any.whl
Size 18.7 kB
Tags Python 2 Python 3
SHA-256 checksum
How to use checksums
bf5752f4c0d61da1f9d8deef0b14f324f04d88053ef35e406b704b2ee0948ebf
BLAKE2b-256 checksum
How to use checksums
801c0790764a34d115708a57cfeb0cd2c4fd967d106d327f4c2cae65df5f2e34
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No

Security for towncrier 17.8.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

17.8.0 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page