rtfc documentation

rtfc

Read the freaking changelog is a tool to manage changelogs and versioning.

As the name implies, rtfc helps you produce clear, well-structured changelogs, leaving your users no excuse for being surprised by what changed between releases.

rtfc is heavily inspired by the great Towncrier project.

Installation

From PyPI:

pip install rtfc

Usage

Configure rtfc in the [tool.rtfc] table of your pyproject.toml (or in an rtfc.toml file), and add the insert marker to your changelog document:

[tool.rtfc]
changelog = "docs/source/changelog.rst"

Changelog
=========

.. rtfc-insert

Changelog entries are individual files created along the changes of a pull request, avoiding the merge conflicts a shared changelog file causes:

$ rtfc new --section bugfix --meta gh_issue=123 --content "Fix a bug."
Created changelog/d0592011.bugfix.rtfc

Each entry holds a TOML frontmatter and the change description, written in the documentation format of your project:

+++
date = 2026-08-06
nonce = "d0592011"
section = "bugfix"

[metadata]
gh_issue = 123
+++
Fix a bug.

Validate the configuration and the entries, typically in CI:

$ rtfc check
OK: 1 valid entries

On release, combine the entries into the changelog. The version block is inserted after the marker, and the entry files are deleted:

$ rtfc build --version 1.2.0
Updated docs/source/changelog.rst

A sphinx extension is also provided, rendering the not-yet-released entries when building your documentation.

Contents:

• Usage
  • rtfc.toml
  • pyproject.toml
  • Setting up a project
  • Workflow
• Configuration
  • changelog
  • directory
  • format
  • sections
  • metadata
  • render.template
  • render.template_file
  • render.entry_template
  • render.entry_template_file
• Command line interface
  • Positional Arguments
  • Sub-commands
• Sphinx extension
  • Setup
  • Usage
• Changelog
  • v0.1.0 (2026-08-06)