Skip to main content

Building newsfiles for your project.

Project description

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

In your project root, add a towncrier.toml file. You can configure your project in two ways. To configure it via an explicit directory, add:

[tool.towncrier]
    directory = "changes"

Alternatively, to configure it relative to a (Python) package directory, add:

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

For the latter, news fragments (see “News Fragments” below) should be in a newsfragments directory under your package. Using the above example, your news fragments would be src/myproject/newsfragments/).

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 create a new news fragment, use the towncrier create command. For example:

towncrier create 123.feature

To produce a draft of the news file, run:

towncrier build --draft

To produce the news file for real, run:

towncrier build

This command will remove the news files (with git rm) and append the built news to the filename specified in towncrier.toml, 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.

Further Options

Towncrier has the following global options, which can be specified in the toml file:

[tool.towncrier]
    package = ""
    package_dir = "."
    single_file = true  # if false, filename is formatted like `title_format`.
    filename = "NEWS.rst"
    directory = "directory/of/news/fragments"
    template = "path/to/template.rst"
    start_line = "start of generated content"
    title_format = "{name} {version} ({project_date})"  # or false if template includes title
    issue_format = "format string for {issue} (issue is the first part of fragment name)"
    underlines: "=-~"
    wrap = false  # Wrap text to 79 characters
    all_bullets = true  # make all fragments bullet points

If a single file is used, the content of this file are overwritten each time.

Furthermore, you can add your own fragment types using:

.. code-block:: toml
[tool.towncrier]
[[tool.towncrier.type]]

directory = “deprecation” name = “Deprecations” showcontent = true

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-19.9.0rc1.tar.gz (25.7 kB view details)

Uploaded Source

Built Distribution

towncrier-19.9.0rc1-py2.py3-none-any.whl (28.4 kB view details)

Uploaded Python 2 Python 3

File details

Details for the file towncrier-19.9.0rc1.tar.gz.

File metadata

  • Download URL: towncrier-19.9.0rc1.tar.gz
  • Upload date:
  • Size: 25.7 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/1.14.0 pkginfo/1.5.0.1 requests/2.22.0 setuptools/40.8.0 requests-toolbelt/0.9.1 tqdm/4.35.0 CPython/3.7.4

File hashes

Hashes for towncrier-19.9.0rc1.tar.gz
Algorithm Hash digest
SHA256 d0c49060522e4b45d02c8ffe0b63e5ffa660830f681446945212e5c66314228b
MD5 b6d5e613f58d10370fa660819a845a9b
BLAKE2b-256 08e08325cf4c5d2ce7e233580dd06976f30bf43a14e81feb6911e15a59d9be53

See more details on using hashes here.

Provenance

File details

Details for the file towncrier-19.9.0rc1-py2.py3-none-any.whl.

File metadata

  • Download URL: towncrier-19.9.0rc1-py2.py3-none-any.whl
  • Upload date:
  • Size: 28.4 kB
  • Tags: Python 2, Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/1.14.0 pkginfo/1.5.0.1 requests/2.22.0 setuptools/40.8.0 requests-toolbelt/0.9.1 tqdm/4.35.0 CPython/3.7.4

File hashes

Hashes for towncrier-19.9.0rc1-py2.py3-none-any.whl
Algorithm Hash digest
SHA256 f0375efce604977b4098c18dc805d5ce0de59b232db8374cb3ca98b078b5afae
MD5 305a7a49c5003a38f0179d58f91aa21a
BLAKE2b-256 28090eced9995338f09f742cc75b56fcc7eef4aa0250919840b9f22df496ddb1

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