Add a Markdown how-to

[hynek]

I believe this fixes #128.

While working on this I've noticed a big problem: the order of the categories is always alphabetical!? This needs to be fixed.

[codecov]

Codecov Report

Base: 100.00% // Head: 100.00% // No change to project coverage 👍

Coverage data is based on head (5728074) compared to base (cd2d434).
Patch has no changes to coverable lines.

Additional details and impacted files

@@            Coverage Diff            @@
##             trunk      #436   +/-   ##
=========================================
  Coverage   100.00%   100.00%           
=========================================
  Files           13        13           
  Lines          600       600           
  Branches       144       144           
=========================================
  Hits           600       600           

Help us with your feedback. Take ten seconds to tell us how you rate us. Have a feature suggestion? Share it here.

☔ View full report at Codecov.
📢 Do you have feedback about the report comment? Let us know in this issue.

[adiroiban]

Thanks. Looks good.

I think we should merge this.

I am not using markdown, but I expect that this is a very common use case.
This is why, in the future we might want to incorporate the template in towcrier.

Maybe have some "predefined" templates, that when connfigured will automatically also set/overwrite the underlines, title_format and issue_format

So that you can have just

   [tool.towncrier]
   directory = "changelog.d"
   filename = "CHANGELOG.md"
   start_string = "<!-- towncrier release notes start -->\n"
   template = "markdown"

When towncrier will see a config with markdown as the value, will not search for that file, but instead use some predefined values, with a template distributed with towncrier.

[adiroiban]

For now is ok.
I expect that Markdown is a common use case, so we might want to have a predefined markdown template, that is maintained by the main dev team.

[adiroiban]

Previously the config was something like this

    [[tool.towncrier.type]]
        directory = "security"
        name = "Security Fixes"
        showcontent = true

    [[tool.towncrier.type]]
        directory = "feature"
        name = "New Features"
        showcontent = true

I guess the main issue is due to pytoml not using an ordered dict.

[hynek]

Ooof yeah you're right. It used to be an array but is a dict now and tomli gives it alphabetically:

{'tool': {'towncrier': {'directory': 'changelog.d',
                        'filename': 'CHANGELOG.md',
                        'fragment': {'added': {'name': 'Added'},
                                     'changed': {'name': 'Changed'},
                                     'deprecated': {'name': 'Deprecated'},
                                     'fixed': {'name': 'Fixed'},
                                     'removed': {'name': 'Removed'},
                                     'security': {'name': 'Security'}},
                        'issue_format': '[#{issue}](https://github.com/twisted/my-project/issues/{issue})',
                        'start_string': '<!-- towncrier release notes start '
                                        '-->\n',
                        'template': 'changelog.d/changelog_template.jinja',
                        'title_format': '## '
                                        '[{version}](https://github.com/twisted/my-project/tree/{version}) '
                                        '- {project_date}',
                        'underlines': ['', '', '']}}}

[adiroiban]

For reference.
This was implemented here https://github.com/twisted/towncrier/pull/370/files

I think the old format is still supported.

---

This looks like a bug for the new format.

[adiroiban]

I am not sure what toml lib we a re using, but it looks like ordered dict are not a thing :)

uiri/toml#2

and also not wanted in the general TOML spec

toml-lang/toml#162

[hynek]

In modern Pythons, dicts are always ordered. This is a deliberate action by tomli based on the spec that you linked. I've opened #437 to track this.

[hynek]

Please don't merge until #438 is merged and I have adapted this to the array style – thanks!

[hynek]

I just realized this one is not dependent on docs being updated so here it is. I've re-done it using the array-style definition.

[adiroiban]

Thanks. All good.

directory instead of file_extension is ugly ... but this life :)

[SmileyChris]

I was working on better markdown integration a while back, just resurrected that stash and made a PR for it: #439

Might be a much easier way to handle markdown formatting...