Usage¶

rtfc can be used a command line interface. A configuration file must be defined where the CLI is invoked. rtfc can be configured in to ways:

rtfc.toml¶

rtfc.toml has the highest priority.

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

pyproject.toml¶

The [tool.rtfc] table can be used in the pyproject.toml of your project [1]:

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

changelog is the only required configuration value. See Configuration for more details.

Documentation format¶

rtfc is not tied to a documentation framework: changelog entries are written in the documentation format of your project, and rtfc only combines them (their content is never parsed). The format configuration value selects the format, which determines the structure rtfc produces (headings, list items, the insert marker comment). reStructuredText (rst) is built in and the default. Other formats can be provided by third-party packages, through the rtfc.formats entry point group.

The examples below use the default rst format.

Setting up a project¶

Besides the configuration file, rtfc expects two things to exist:

the entry directory (changelog/ by default), holding the changelog entry files until they are released.
the changelog file, containing the insert marker comment after which released versions are inserted:
```
Changelog
=========

.. rtfc-unreleased::

.. rtfc-insert
```
The rtfc-unreleased directive is optional, it renders the unreleased entries when building the documentation with the sphinx extension.

Workflow¶

Create a changelog entry along the changes of a pull request with the new command. When run from a terminal, missing values are prompted for, and the entry is opened in EDITOR:

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

Validate the configuration and all entries with the check command, typically in CI:

$ rtfc check
OK: 3 valid entries

On release, combine the entries into the changelog with the build command. The release notes are inserted after the marker and the entry files are deleted. Use --dry-run first to preview the release notes without touching anything:

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

Entries can also be exported in alternative formats, e.g. as markdown for GitHub or GitLab release notes.

See the command line interface reference for all options.

Footnotes