Giters

twisted / towncrier

Manage the release notes for your project.

Home Page:https://towncrier.readthedocs.io

Geek Repo:Geek Repo

Github PK Tool:Github PK Tool

Markdown docs use 'custom' template and don't show/mention default available

EFord36 opened this issue · comments

commented

Hi,

(PR incoming, but opening this first so I can get the news snippet right).

The Markdown docs specify how to set up a custom changelog.d/changelog_template.jinja file, but these docs predate #483 , which will use the default.md template for a .md changelog file by default - so for users, it would likely just be simpler to depend on a default template than to copy/paste the 'custom' one specified in the docs.

The default.md template seems to also add complexity to handle more cases, and has another couple of desirable features I found, so is likely to be preferred anyway:

  • the 'custom' template from the docs will add trailing whitespace at the end of lines that are 'orphan snippets' without an issue
  • the default.md template puts brackets around issues in a way that seems to match Keep A Changelog more closely, and matching Keep A Changelog is (part of) the objective of that page in the docs.

I think it would be useful for it to be clear to users who want to use markdown that they don't need to configure a template themselves to get towcrier working with markdown - either by switching the docs to just use the default template, or by explicit discussion of this option in the docs.

I suspect the current situation is just a historical consequence of #436 coming a good while before #483 rather than a deliberate choice, but please correct me if I'm wrong!

While I'm writing, thanks for towncrier, I've found it very useful!

commented

Thanks for the report.

A lot of things are "historical"

towncrier started as a small tool to help manage the release notes for twisted/twisted
then it was moved as a separate project, but RST was still the only format.

There was no "overarching vision" for the tool...so there is a lot of patchwork here.

I think that everybody would be happy to work towards making Markdown a first class markup for towncrier.

Right now RST is first class, and Markdown is kind of second...
but .md support is getting better

Happy to receive any PR to improve the docs, or configuration or usage experience.

Cheers

commented

Also, thanks for the link to https://keepachangelog.com/en/1.1.0/ - I wasn't aware of this.

I think it would be nice to add a link to this page , somewhere in the towncrier docs

Quite often I have to explain to developers that the changelog is not the git commit log :)

So I am happy to have some website where I can send people to.

Also, happy to see any soft of standardization effort :)

commented

Thanks for responding! Keep A Changelog is already linked from this page: https://towncrier.readthedocs.io/en/stable/markdown.html at the top, but I guess it's still relevant to users of towncrier who use ReST rather than markdown, so might be worth linking elsewhere too.