Skip to main content

No project description provided

Project description

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

In your project root, add a towncrier.ini file, with the contents:

[towncrier]
; Your project name
package = mypackage
; Where your project is kept -- current dir by default
package_dir = src/
; The filename that it will write to, relative to the current dir
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”.

Your project needs a __version__ for it to work, in the top level package. This can be either a string literal, or an Incremental version.

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.

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.

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

towncrier-15.1.0.tar.gz (8.9 kB view details)

Uploaded Source

Built Distribution

towncrier-15.1.0-py3-none-any.whl (13.4 kB view details)

Uploaded Python 3

File details

Details for the file towncrier-15.1.0.tar.gz.

File metadata

  • Download URL: towncrier-15.1.0.tar.gz
  • Upload date:
  • Size: 8.9 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No

File hashes

Hashes for towncrier-15.1.0.tar.gz
Algorithm Hash digest
SHA256 ae0a45b1248aa5f095f363419e65e2156ba61bd23b1abd56d4a15b63b10010aa
MD5 da77a01f3bead54f54389b5c06548785
BLAKE2b-256 f90de17ddc9c046b2bca79c96e53e850d703bec302e9fb9ec21470b14574b543

See more details on using hashes here.

Provenance

File details

Details for the file towncrier-15.1.0-py3-none-any.whl.

File metadata

File hashes

Hashes for towncrier-15.1.0-py3-none-any.whl
Algorithm Hash digest
SHA256 761c9bebf5d1d35d007b2bc3af68c536ca5e9d13ee9ebff592c3ff74b7293213
MD5 15a02d54980d54d8b60de8accbf2bd18
BLAKE2b-256 308c6f322c5a8b4dad2bbc2f9499ceafd3ad3c98e401c9e6577db49ab042cd3e

See more details on using hashes here.

Provenance

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page