towncrier

Towncrier provides default types: feature, bugfix, doc, removal, and misc. You can define custom types using two methods:

Method 1: TOML Tables (Alphabetical Order)

Use [tool.towncrier.fragment.<type>]. Types are rendered in alphabetical order.

• name: Description used in the news file (defaults to capitalized type).
• showcontent: Boolean, whether to include fragment content (default true).
• check: Boolean, whether towncrier check validates this type (default true).

Method 2: TOML Array (Defined Order)

Use [[tool.towncrier.type]]. This allows you to control the order of types. Do not use this method if you are also using the fragment table method.

• name (Required): The description used in the news file.
• directory: The directory/category of the fragment (defaults to name.lower()).
• showcontent: Boolean, whether to include content (default true).
• check: Boolean, whether towncrier check validates this type (default true).

# Example using Tables (Alphabetical)
[tool.towncrier.fragment.feat]
[tool.towncrier.fragment.fix]

[tool.towncrier.fragment.chore]
name = "Other Tasks"
showcontent = false

# Example using Array (Ordered)
[[tool.towncrier.type]]
name = "Deprecations"

[[tool.towncrier.type]]
directory = "chore"
name = "Other Tasks"
showcontent = false

News fragments are categorized by 'type'. The default types are:

• feature: New features.
• bugfix: Bug fixes.
• doc: Documentation improvements.
• removal: Deprecation or removal of public API.
• misc: Closed issues not of interest to users.

Fragment Naming

Fragments are identified by a filename containing a unique ID (like an issue number) and the type (e.g., 1234.bugfix). The file extension is ignored.

Orphan Fragments: To create a fragment without an issue ID, prefix the filename with + (e.g., +random.bugfix.rst). These appear at the end of their category.

Commands

• Manual creation: Create a file in your fragments directory.
• towncrier create: Use this command to generate fragments.
• towncrier create --edit: Opens your editor to write the fragment content.

# Create a bugfix fragment manually
echo 'Fixed a thing!' > src/myproject/newsfragments/1234.bugfix

# Create a doc fragment using the CLI
towncrier create --content 'Can also be rst as well!' 3456.doc.rst

# Create an orphan fragment
echo 'Fixed an unreported thing!' > src/myproject/newsfragments/+anything.bugfix

# Create and edit a fragment
towncrier create --edit 2.misc.rst

When managing multiple independent projects within a single repository (a monorepo), you can use a single towncrier.toml file to manage all of them.

To achieve this, you must leave the package and name configuration fields empty in towncrier.toml. This is because these fields can only hold one value, and in a monorepo, each project has its own package name and identity. Instead of relying on the config file for project identity, you must specify the project directory using the --dir flag during CLI operations.

Example Directory Structure:

repo
├── project_a
│   ├── newsfragments
│   │   └── 123.added
│   ├── project_a
│   │   └── __init__.py
│   └── NEWS.rst
├── project_b
│   ├── newsfragments
│   │   └── 120.bugfix
│   ├── project_b
│   │   └── __init__.py
│   └── NEWS.rst
└── towncrier.toml

towncrier.toml configuration:

[tool.towncrier]
# It's important to keep these config fields empty
# because we have more than one package/name to manage.
package = ""
name = ""

Follow these steps to manage a Markdown changelog:

1. Initialize the fragment directory: Create the directory specified in your configuration (e.g., mkdir changelog.d).
2. Initialize the changelog file: Create CHANGELOG.md with an explanatory header and include the start_string marker defined in your config.
3. Create news fragments: Use the towncrier create command to add individual changes. The filename suffix (e.g., .added.md, .fixed.md) determines which section the fragment will appear under.
4. Build the changelog: Run towncrier build with the --version flag to aggregate all fragments into the main changelog file.

Example Workflow:

# Create fragments
towncrier create -c "Added a cool feature!" 1.added.md
towncrier create -c "Fixed a bug!" 5.fixed.md

# Build the changelog for version 1.0.0
towncrier build --yes --version 1.0.0

towncrier create -c "Added a cool feature!" 1.added.md
towncrier create -c "Changed a behavior!" 2.changed.md
towncrier create -c "Deprecated a module!" 3.deprecated.md
towncrier create -c "Removed a square feature!" 4.removed.md
towncrier create -c "Fixed a bug!" 5.fixed.md
towncrier create -c "Fixed a security issue!" 6.security.md
towncrier create -c "Fixed a security issue!" 7.security.md
towncrier create -c "A fix without an issue number!" +something-unique.fixed.md

towncrier build --yes --version 1.0.0