Sane defaults for `CHANGELOG.md`

[matteosantama]

The documentation section How to Keep a Changelog in Markdown is very nice, but the required configuration is rather verbose

[tool.towncrier]
directory = "changelog.d"
filename = "CHANGELOG.md"
start_string = "<!-- towncrier release notes start -->\n"
underlines = ["", "", ""]
title_format = "## [{version}](https://github.com/twisted/my-project/tree/{version}) - {project_date}"
issue_format = "[#{issue}](https://github.com/twisted/my-project/issues/{issue})"

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

[[tool.towncrier.type]]
directory = "removed"
name = "Removed"
showcontent = true

[[tool.towncrier.type]]
directory = "deprecated"
name = "Deprecated"
showcontent = true

[[tool.towncrier.type]]
directory = "added"
name = "Added"
showcontent = true

[[tool.towncrier.type]]
directory = "changed"
name = "Changed"
showcontent = true

[[tool.towncrier.type]]
directory = "fixed"
name = "Fixed"
showcontent = true

There are two things towncrier could do to shorten this, presumably, very popular configuration.

1. The documentation says showcontent = true by default when using TOML tables, but this is wrong. If you comment out showcontent = true in the above configuration, you get a missing key error when building the changelog.
2. You should only need to specify directory or name in the above configuration. The other can be reasonably inferred (with an option to override this behavior by specifying both).

Would the maintainers of towncrier be open to receiving a PR with these two changes? They would both be fully backward-compatible.

[adiroiban]

Hi Matteo.

Many thanks for the report.

The documentation says showcontent = true by default when using TOML tables, but this is wrong. If you comment out showcontent = true in the above configuration, you get a missing key error when building the changelog.

Happy to review and approve a PR for this.

---

You should only need to specify directory or name in the above configuration. The other can be reasonably inferred (with an option to override this behavior by specifying both).

Make sense.

I think that we can go with only name.

The directory can then be inferred.

Side note. The directory is a bad name anyway... so happy to somehow get it out of the way :p

Happy to review and approve a PR for this.

---

Regarding

underlines = ["", "", ""]
title_format = "## {version} - {project_date}"
issue_format = "#{issue}"

I would love to see the option to move the format outside of the configuration file and into the template file.

We can still configure the issue URL and version URL in the config file

[matteosantama]

Great! I'll put together a PR for your review.

I would love to see the option to move the format outside of the configuration file and into the template file.

If I understand you correctly, I would add a new template file keep_a_changelog.md and then update the documentation to promote the usage as

[tool.towncrier]
directory = "changelog.d"
filename = "CHANGELOG.md"
template = "towncrier:keep_a_changelog.md"
issue_url = "https://github.com/twisted/my-project/issues/{issue}"
version_url = "https://github.com/twisted/my-project/tree/{version}"

[[tool.towncrier.type]]
name = "Security"

[[tool.towncrier.type]]
name = "Removed"

[[tool.towncrier.type]]
name = "Deprecated"

[[tool.towncrier.type]]
name = "Added"

[[tool.towncrier.type]]
name = "Changed"

[[tool.towncrier.type]]
name = "Fixed"

Is that what you had in mind? Is it still necessary to specify the custom types if we request the keep_a_changelog.md template?

[adiroiban]

Great! I'll put together a PR for your review.

Thanks. Looking forward to the PR.

---

I have created a separate issue and we can see how we can simplify the config.