News Fragments for towncrier

Work with towncrier news fragments in VS Code. towncrier builds a changelog from small files, one per change, whose names carry the information: 123.feature.md is a new feature for issue 123, +a1b2c3d4.bugfix.rst is a bug fix not tied to an issue. A misspelt name is not an error for towncrier build: the file is silently left out of the changelog. This extension creates fragments with the right name in the right folder, shows what is pending, and points out files towncrier would skip or stop on.

Features

• New News Fragment command (command palette, the + button in the view, or the + next to a type). Pick the type (with its changelog heading), enter the issue number, or leave it empty for a fragment that is not tied to an issue, and type the text (or leave it empty and write it in the editor). The file is created with the name towncrier create would use: <issue>.<type> plus .md / .rst when your changelog is Markdown / reStructuredText (create_add_extension), <orphan_prefix><8 hex digits>.<type> without an issue, and a counter (123.feature.1.md) when the name is taken. Unlike towncrier create, it also skips names that would clash with a fragment for the same issue and type written differently (0123.feature and 123.feature.md), which would make towncrier build stop.
• Problems for fragment files in the fragments folder:
  • names with no known type (123.feeture.md, feature.123, notes.txt): towncrier build silently skips them and towncrier check fails; with ignore set, build stops on them, so they are errors;
  • two files with the same issue, type and counter (101.feature.md and 0101.feature): towncrier build stops with "multiple files for 101.feature";
  • issues that do not match issue_pattern (build stops);
  • empty fragments, whose changelog entry would be a bare issue link or an empty bullet (not reported for types such as misc whose text is not shown);
  • folders inside the fragments folder that towncrier check stops on.
• Quick fixes that rename a file when the intended name is clear: a misspelt or differently-cased type (feeture → feature, Feature → feature, fix → bugfix), type and issue swapped (feature.123 → 123.feature), or a free counter for a duplicate.
• News Fragments view in the Explorer: each project, its sections (if it has several), its types with the number of pending fragments, and each fragment with its issue and first line. Click to open. Files that towncrier would not pick up are listed separately. Nothing in the view deletes or changes files.

How the configuration is read

The extension follows towncrier 26.9's own rules (checked against its source and by running it):

• A folder's towncrier.toml is used if it exists, otherwise its pyproject.toml if that has a [tool.towncrier] table. Settings are always under [tool.towncrier], also in towncrier.toml.
• Fragments folder: directory relative to the config file; otherwise <package_dir>/<package>/newsfragments, where package falls back to [project] name from pyproject.toml. [[tool.towncrier.section]] entries add their path to it.
• Types: the five defaults (feature, bugfix, doc, removal, misc), or [[tool.towncrier.type]] (the file name part is directory, else the lower-cased name), or [tool.towncrier.fragment.<type>] (which wins when both are present).
• Always skipped: .gitignore, .gitkeep, .keep, README, README.md, README.rst, the template file, and anything matching ignore.

Settings

The New News Fragment command (towncrierFragments.create) also accepts an argument object, handy for keybindings: { "type": "bugfix", "issue": "", "content": "...", "section": "", "project": "/path/to/project" }. Anything left out is asked for.

Known limitations

• The extension does not run towncrier; it reads the config files itself. A .towncrier.toml file is not read because towncrier itself does not read it. --config / --dir command-line overrides are not known to it.
• issue_pattern is evaluated as a JavaScript regular expression; Python-only syntax is skipped.
• Only local folders are supported (not virtual workspaces). Hidden files that are not fragments (such as .DS_Store) are not reported.
• When the fragments folder is the project folder itself, only names that look like a misspelt fragment are reported, so ordinary project files are not flagged.

Privacy

Everything happens locally: the extension reads your config and fragment files and writes only the fragments you create. It sends nothing over the network and starts no programs.

Feedback

Problems and ideas are welcome on the Marketplace page (Q & A / rating). This is an independent extension: it is not an official towncrier product and is not affiliated with or endorsed by the towncrier authors or the Twisted project. It was built with AI assistance by Honestrel and is checked by automated tests in a real VS Code.