Default markdown template #483

SmileyChris · 2023-03-01T00:04:16Z

Description

Provides a default markdown template.

Towncrier will use this as the default template if the configured filename ends with .md. For any other filename, default.rst will continue to be used. For example:

filename = "CHANGES.md"

This is a simplification of earlier work in #439.

Changes to `load.py`

In load.py, the Config dataclass now has defaults, rather than them being dispersed elsewhere in logic.

The parse_toml function has been reorganized for clarity (keeping the same functionality).

Better configuration docs

The documentation for configuration settings was rewritten for completeness, better accuracy of defaults, and missing features.

It also better highlights different required settings for python vs non-python projects.

Reference style link support

The only thing different in the markdown default template than the restructured text one is the ability to use markdown reference style links if the config is set to issue_format = "[{issue}]: https://<bug tracker>/{issue}".

For example, with issue_format = "[{issue}]: https://github.com/twisted/towncrier/issues/{issue}":

...
### Features

- Foo added. ([2], [9], [72])
- More stuff ([3])
- Stuff! ([4])

[2]: https://github.com/twisted/towncrier/issues/2
[3]: https://github.com/twisted/towncrier/issues/3
[4]: https://github.com/twisted/towncrier/issues/4
[9]: https://github.com/twisted/towncrier/issues/9
[72]: https://github.com/twisted/towncrier/issues/72

This is why there's a new issues_by_category template context variable built and passed to the template.

Checklist

Make sure changes are covered by existing or new tests.
For at least one Python version, make sure local test run is green.
Create a file in src/towncrier/newsfragments/. Describe your
change and include important information. Your change will be included in the public release notes.
Make sure all GitHub Actions checks are green (they are automatically checking all of the above).
Ensure docs/tutorial.rst is still up-to-date.
If you add new configuration options (or change the meaning of existing ones), make sure docs/configuration.rst reflects those changes.

codecov · 2023-03-01T00:06:53Z

Codecov Report

Patch coverage: 100.00% and project coverage change: +0.15 🎉

Comparison is base (70da86f) 99.84% compared to head (63b6257) 100.00%.

❗ Current head 63b6257 differs from pull request most recent head 4fd6453. Consider uploading reports for the commit 4fd6453 to get more accurate results

Additional details and impacted files

@@             Coverage Diff             @@
##            trunk      #483      +/-   ##
===========================================
+ Coverage   99.84%   100.00%   +0.15%     
===========================================
  Files          13        13              
  Lines         631       635       +4     
  Branches      146       153       +7     
===========================================
+ Hits          630       635       +5     
+ Partials        1         0       -1

Impacted Files	Coverage Δ
src/towncrier/_builder.py	`100.00% <100.00%> (ø)`
src/towncrier/_settings/load.py	`100.00% <100.00%> (ø)`

... and 2 files with indirect coverage changes

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

for more information, see https://pre-commit.ci

hynek

oof this is a big boy!

I'm really a bit anxious about it (not by your fault mind you, the code is what it is), but I guess we should trust the tests?

docs/tutorial.rst

src/towncrier/_settings/load.py

src/towncrier/newsfragments/483.feature.rst

src/towncrier/test/test_settings.py

src/towncrier/test/test_format.py

Markdown caps, test formatting Co-authored-by: Hynek Schlawack <hs@ox.cx>

hynek

Greetings from the PyCon US sprints!

I've realized that we never documented the fact we use semantic linefeeds so I've opened #500

docs/configuration.rst

src/towncrier/newsfragments/483.feature.rst

src/towncrier/test/test_format.py

src/towncrier/test/test_settings.py

docs/configuration.rst

Co-authored-by: Hynek Schlawack <hs@ox.cx>

hynek

I've fixed the doc link that I suggested incorrectly, but for some reason CI didn't run. It fails tho due to the ordereddict stuff i mention inline, so I've reverted that commit for now and it passes for me locally.

Either way you'll have to resolve the conflicts that have accumulated. :-/ (on the bright side the revert simplified the conflict somewhat)

src/towncrier/_builder.py

src/towncrier/test/test_format.py

src/towncrier/newsfragments/483.feature

src/towncrier/_settings/load.py

SmileyChris · 2023-05-02T03:41:12Z

Oh windows, why are you being a jerk?

…ce template

…default-markdown-template

SmileyChris · 2023-05-03T22:31:17Z

I have just realized, that this makes no sense with Markdown (you'd have to use an HTML comment like \n) and that we don't have a test for the case where an existing news file is amended – correct?

If things are supposed to work out of the box, I guess you'll have to special-case this too (and add a test for it).

Ok, special-cased and added tests.

hynek

this is not an exhaustive review, because i'm on a road trip in the middle of nowhere and being dragged off but i'm trying to keep things moving 😅

docs/customization/newsfile.rst

src/towncrier/test/test_build.py

(and fix typo in documented markdown start_string)

for more information, see https://pre-commit.ci

hynek

OK I think this should be good to merge, I don't think another round of a full review by me would do much good and we'd just accumulate more conflicts.

It should probably be like three PRs, but let's fix problems in post. 😅

Bumps [towncrier](https://github.com/twisted/towncrier) from 22.8.0 to 23.6.0. <details> <summary>Release notes</summary> <p><em>Sourced from <a href="https://github.com/twisted/towncrier/releases">towncrier's releases</a>.</em></p> <blockquote> <h2>Towncrier 23.6.0</h2> <h1>towncrier 23.6.0 (2023-06-06)</h1> <p>This is the last release to support Python 3.7.</p> <h2>Features</h2> <ul> <li> <p>Make <code>towncrier create</code> use the fragment counter rather than failing on existing fragment names.</p> <p>For example, if there is an existing fragment named <code>123.feature</code>, then <code>towncrier create 123.feature</code> will now create a fragment named <code>123.feature.1</code>. (<a href="https://redirect.github.com/twisted/towncrier/issues/475">#475</a>)</p> </li> <li> <p>Provide a default Markdown template if the configured filename ends with <code>.md</code>.</p> <p>The Markdown template uses the same rendered format as the default <em>reStructuredText</em> template, but with a Markdown syntax. (<a href="https://redirect.github.com/twisted/towncrier/issues/483">#483</a>)</p> </li> <li> <p>Towncrier no longer depends on setuptools & uses importlib.resources (or its backport) instead. (<a href="https://redirect.github.com/twisted/towncrier/issues/496">#496</a>)</p> </li> <li> <p>Added pre-commit hooks for checking and updating news in projects using pre-commit. (<a href="https://redirect.github.com/twisted/towncrier/issues/498">#498</a>)</p> </li> <li> <p>Calling <code>towncrier check</code> without an existing configuration, will just show only an error message.</p> <p>In previous versions, a traceback was generated instead of the error message. (<a href="https://redirect.github.com/twisted/towncrier/issues/501">#501</a>)</p> </li> </ul> <h2>Bugfixes</h2> <ul> <li> <p>Fix creating fragment in a section not adding random characters.</p> <p>For example, <code>towncrier create some_section/+.feature</code> should end up as a fragment named something like <code>news/some_section/+a4e22da1.feature</code>. (<a href="https://redirect.github.com/twisted/towncrier/issues/468">#468</a>)</p> </li> <li> <p>Fix the ReadTheDocs build for <code>towncrier</code> which was broken due to the python version in use being 3.8. Upgrade to 3.11. (<a href="https://redirect.github.com/twisted/towncrier/issues/509">#509</a>)</p> </li> </ul> <h2>Improved Documentation</h2> <ul> <li>Moved man page to correct section (<a href="https://redirect.github.com/twisted/towncrier/issues/470">#470</a>)</li> <li>Update link to Quick Start in configuration.html to point to Tutorial instead. (<a href="https://redirect.github.com/twisted/towncrier/issues/504">#504</a>)</li> <li>Add a note about the build command's <code>--version</code> requiring the command to be explicitly passed. (<a href="https://redirect.github.com/twisted/towncrier/issues/511">#511</a>)</li> <li>Fix typos in the Pre-Commit docs. (<a href="https://redirect.github.com/twisted/towncrier/issues/512">#512</a>)</li> </ul> <h2>Misc</h2> <ul> <li><a href="https://redirect.github.com/twisted/towncrier/issues/459">#459</a>, <a href="https://redirect.github.com/twisted/towncrier/issues/462">#462</a>, <a href="https://redirect.github.com/twisted/towncrier/issues/472">#472</a>, <a href="https://redirect.github.com/twisted/towncrier/issues/485">#485</a>, <a href="https://redirect.github.com/twisted/towncrier/issues/486">#486</a>, <a href="https://redirect.github.com/twisted/towncrier/issues/487">#487</a>, <a href="https://redirect.github.com/twisted/towncrier/issues/488">#488</a>, <a href="https://redirect.github.com/twisted/towncrier/issues/495">#495</a>, <a href="https://redirect.github.com/twisted/towncrier/issues/497">#497</a>, <a href="https://redirect.github.com/twisted/towncrier/issues/507">#507</a>, <a href="https://redirect.github.com/twisted/towncrier/issues/1117">#1117</a>, <a href="https://redirect.github.com/twisted/towncrier/issues/513">#513</a></li> </ul> <h2>Towncrier 23.6.0rc1</h2> <h1>towncrier 23.6.0rc1 (2023-06-05)</h1> <p>This is the last release to support Python 3.7.</p> <h2>Features</h2> <ul> <li>Make <code>towncrier create</code> use the fragment counter rather than failing on existing fragment names.</li> </ul>  </blockquote> <p>... (truncated)</p> </details> <details> <summary>Changelog</summary> <p><em>Sourced from <a href="https://github.com/twisted/towncrier/blob/trunk/NEWS.rst">towncrier's changelog</a>.</em></p> <blockquote> <h1>towncrier 23.6.0 (2023-06-06)</h1> <p>This is the last release to support Python 3.7.</p> <h2>Features</h2> <ul> <li> <p>Make <code>towncrier create</code> use the fragment counter rather than failing on existing fragment names.</p> <p>For example, if there is an existing fragment named <code>123.feature</code>, then <code>towncrier create 123.feature</code> will now create a fragment named <code>123.feature.1</code>. (<code>[#475](twisted/towncrier#475) <https://github.com/twisted/towncrier/issues/475></code>_)</p> </li> <li> <p>Provide a default Markdown template if the configured filename ends with <code>.md</code>.</p> <p>The Markdown template uses the same rendered format as the default <em>reStructuredText</em> template, but with a Markdown syntax. (<code>[#483](twisted/towncrier#483) <https://github.com/twisted/towncrier/issues/483></code>_)</p> </li> <li> <p>Towncrier no longer depends on setuptools & uses importlib.resources (or its backport) instead. (<code>[#496](twisted/towncrier#496) <https://github.com/twisted/towncrier/issues/496></code>_)</p> </li> <li> <p>Added pre-commit hooks for checking and updating news in projects using pre-commit. (<code>[#498](twisted/towncrier#498) <https://github.com/twisted/towncrier/issues/498></code>_)</p> </li> <li> <p>Calling <code>towncrier check</code> without an existing configuration, will just show only an error message.</p> <p>In previous versions, a traceback was generated instead of the error message. (<code>[#501](twisted/towncrier#501) <https://github.com/twisted/towncrier/issues/501></code>_)</p> </li> </ul> <h2>Bugfixes</h2> <ul> <li> <p>Fix creating fragment in a section not adding random characters.</p> <p>For example, <code>towncrier create some_section/+.feature</code> should end up as a fragment named something like <code>news/some_section/+a4e22da1.feature</code>. (<code>[#468](twisted/towncrier#468) <https://github.com/twisted/towncrier/issues/468></code>_)</p> </li> <li> <p>Fix the ReadTheDocs build for <code>towncrier</code> which was broken due to the python version in use being 3.8. Upgrade to 3.11. (<code>[#509](twisted/towncrier#509) <https://github.com/twisted/towncrier/issues/509></code>_)</p> </li> </ul> <h2>Improved Documentation</h2> <ul> <li>Moved man page to correct section (<code>[#470](twisted/towncrier#470) <https://github.com/twisted/towncrier/issues/470></code>_)</li> <li>Update link to Quick Start in configuration.html to point to Tutorial instead. (<code>[#504](twisted/towncrier#504) <https://github.com/twisted/towncrier/issues/504></code>_)</li> <li>Add a note about the build command's <code>--version</code> requiring the command to be explicitly passed. (<code>[#511](twisted/towncrier#511) <https://github.com/twisted/towncrier/issues/511></code>_)</li> <li>Fix typos in the Pre-Commit docs. (<code>[#512](twisted/towncrier#512) <https://github.com/twisted/towncrier/issues/512></code>_)</li> </ul> <h2>Misc</h2> <ul> <li><code>[#459](twisted/towncrier#459) <https://github.com/twisted/towncrier/issues/459></code><em>, <code>[#462](twisted/towncrier#462) <https://github.com/twisted/towncrier/issues/462></code></em>, <code>[#472](twisted/towncrier#472) <https://github.com/twisted/towncrier/issues/472></code><em>, <code>[#485](twisted/towncrier#485) <https://github.com/twisted/towncrier/issues/485></code></em>, <code>[#486](twisted/towncrier#486) <https://github.com/twisted/towncrier/issues/486></code><em>, <code>[#487](twisted/towncrier#487) <https://github.com/twisted/towncrier/issues/487></code></em>, <code>[#488](twisted/towncrier#488) <https://github.com/twisted/towncrier/issues/488></code><em>, <code>[#495](twisted/towncrier#495) <https://github.com/twisted/towncrier/issues/495></code></em>, <code>[#497](twisted/towncrier#497) <https://github.com/twisted/towncrier/issues/497></code><em>, <code>[#507](twisted/towncrier#507) <https://github.com/twisted/towncrier/issues/507></code></em>, <code>[#1117](https://github.com/twisted/towncrier/issues/1117) <https://github.com/twisted/towncrier/issues/1117></code><em>, <code>[#513](twisted/towncrier#513) <https://github.com/twisted/towncrier/issues/513></code></em></li> </ul> <p>towncrier 22.12.0 (2022-12-21)</p>  </blockquote> <p>... (truncated)</p> </details> <details> <summary>Commits</summary> <ul> <li><a href="https://github.com/twisted/towncrier/commit/22a5b015e6404900bfaed4d218cacbd09fc43916"><code>22a5b01</code></a> Update for final release.</li> <li><a href="https://github.com/twisted/towncrier/commit/0d9f08708a29a65050c907995e05180d5320fa6f"><code>0d9f087</code></a> Fix news file.</li> <li><a href="https://github.com/twisted/towncrier/commit/32d7034b82bef8b9f36b6aaec2e9c0de328de222"><code>32d7034</code></a> Remove deploy env requirement.</li> <li><a href="https://github.com/twisted/towncrier/commit/13e6d0c52e5dd63bf6fbf5434731dc4997ecfc82"><code>13e6d0c</code></a> Conditionally run the whole publish.</li> <li><a href="https://github.com/twisted/towncrier/commit/6b9b85a252cc10a40d024710777df48b53740b9a"><code>6b9b85a</code></a> Add dedicated environment.</li> <li><a href="https://github.com/twisted/towncrier/commit/3deaebd35a38bf89e1e0d92bf7822b3ffa61bda0"><code>3deaebd</code></a> Add a top title to the release notes.</li> <li><a href="https://github.com/twisted/towncrier/commit/a94f23c5e3e410bffd44cefbd961192d28fe76f1"><code>a94f23c</code></a> Fix NEWS.rst formatting.</li> <li><a href="https://github.com/twisted/towncrier/commit/3ba6cd1a1830d53266129770556c3d3ea593fcd6"><code>3ba6cd1</code></a> Include the release notes in the docs to make it easyier to review the RST fo...</li> <li><a href="https://github.com/twisted/towncrier/commit/1888debeb12afef9406ac997ad1f9e554423832c"><code>1888deb</code></a> Add info about 3.7.</li> <li><a href="https://github.com/twisted/towncrier/commit/b7a561cf5a85fce14e4abc1ea17d8d9ee59d2e60"><code>b7a561c</code></a> Update for release candidate.</li> <li>Additional commits viewable in <a href="https://github.com/twisted/towncrier/compare/22.8.0...23.6.0">compare view</a></li> </ul> </details> <br /> [![Dependabot compatibility score](https://dependabot-badges.githubapp.com/badges/compatibility_score?dependency-name=towncrier&package-manager=pip&previous-version=22.8.0&new-version=23.6.0)](https://docs.github.com/en/github/managing-security-vulnerabilities/about-dependabot-security-updates#about-compatibility-scores) Dependabot will resolve any conflicts with this PR as long as you don't alter it yourself. You can also trigger a rebase manually by commenting `@dependabot rebase`. [//]: # (dependabot-automerge-start) [//]: # (dependabot-automerge-end) --- <details> <summary>Dependabot commands and options</summary> <br /> You can trigger Dependabot actions by commenting on this PR: - `@dependabot rebase` will rebase this PR - `@dependabot recreate` will recreate this PR, overwriting any edits that have been made to it - `@dependabot merge` will merge this PR after your CI passes on it - `@dependabot squash and merge` will squash and merge this PR after your CI passes on it - `@dependabot cancel merge` will cancel a previously requested merge and block automerging - `@dependabot reopen` will reopen this PR if it is closed - `@dependabot close` will close this PR and stop Dependabot recreating it. You can achieve the same result by closing it manually - `@dependabot ignore this major version` will close this PR and stop Dependabot creating any more for this major version (unless you reopen the PR or upgrade to it yourself) - `@dependabot ignore this minor version` will close this PR and stop Dependabot creating any more for this minor version (unless you reopen the PR or upgrade to it yourself) - `@dependabot ignore this dependency` will close this PR and stop Dependabot creating any more for this dependency (unless you reopen the PR or upgrade to it yourself) </details> --------- Signed-off-by: dependabot[bot] <support@github.com> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> Co-authored-by: dependabot[bot] <dependabot[bot]@users.noreply.github.com> Co-authored-by: Sam Bull <git@sambull.org>

SmileyChris and others added 5 commits March 21, 2023 15:42

Add default markdown template

aee6fd2

Update tutorial.rst to mention markdown

cc27dea

[pre-commit.ci] auto fixes from pre-commit.com hooks

c952d17

for more information, see https://pre-commit.ci

Typing fixes, fix template issue, full test coverage

94d8a26

Add newsfragment

d2bb513

SmileyChris force-pushed the feature/default-markdown-template branch from 388c3c4 to d2bb513 Compare March 21, 2023 02:42

SmileyChris marked this pull request as ready for review March 21, 2023 03:06

SmileyChris requested a review from a team as a code owner March 21, 2023 03:06

hynek requested changes Apr 3, 2023

View reviewed changes

hynek mentioned this pull request Apr 3, 2023

build: if draft, return early #486

Merged

7 tasks

hynek and others added 2 commits April 4, 2023 10:46

Merge branch 'trunk' into feature/default-markdown-template

63b6257

Apply suggestions from code review

c7cd296

Markdown caps, test formatting Co-authored-by: Hynek Schlawack <hs@ox.cx>

hynek mentioned this pull request Apr 26, 2023

Document semantic linefeeds in CONTRIBUTING.rst #500

Merged

hynek requested changes Apr 26, 2023

View reviewed changes

SmileyChris and others added 9 commits April 27, 2023 12:26

Update docs/tutorial.rst

9edaf7b

Co-authored-by: Hynek Schlawack <hs@ox.cx>

Update docs/configuration.rst

09b68f0

Co-authored-by: Hynek Schlawack <hs@ox.cx>

towncrier doesn't use .rst extensions for fragments

6d97f57

Applying suggested changes

744387e

"Version" doc improvements

1aaea1b

Another change for consistency in docs

1b22755

Remove ordereddict and redundant os.mkdirs

a9e07fa

Make Config.underlines a tuple by default

89b72fd

Fix what Github suggestions messed up

7740059

hynek requested changes Apr 27, 2023

View reviewed changes

src/towncrier/_builder.py Outdated Show resolved Hide resolved

hynek reviewed Apr 27, 2023

View reviewed changes

src/towncrier/test/test_format.py Outdated Show resolved Hide resolved

hynek reviewed Apr 27, 2023

View reviewed changes

src/towncrier/newsfragments/483.feature Outdated Show resolved Hide resolved

hynek reviewed Apr 27, 2023

View reviewed changes

src/towncrier/_settings/load.py Outdated Show resolved Hide resolved

SmileyChris added 2 commits May 2, 2023 08:48

Fix dicts that were OrderedDicts

be669c0

Fix documentation link

d2676a9

SmileyChris added 2 commits May 3, 2023 11:13

Make ruff's sort work the same as actual isort

8d429ac

Make config.template use a tuple instead of a string if it's a resour…

bb3c6b7

…ce template

This was referenced May 3, 2023

Update configuration.rst to fix broken link to quickstart.html #504

Merged

Support nested sections #490

Closed

traceback on missing configuration #441

Open

SmileyChris added 4 commits May 4, 2023 10:16

Improve docs for directory configuration key

c517e65

Document template configuration key

8c4ebea

Change default start_string configuration when using markdown

a6afc70

Merge commit '622ba4f8806531cb69ac0fb5364cecd69a5752dc' into feature/…

d50a2d7

…default-markdown-template

SmileyChris requested a review from hynek May 3, 2023 22:32

hynek requested changes May 3, 2023

View reviewed changes

docs/customization/newsfile.rst Outdated Show resolved Hide resolved

src/towncrier/test/test_build.py Outdated Show resolved Hide resolved

src/towncrier/test/test_build.py Outdated Show resolved Hide resolved

SmileyChris and others added 7 commits May 4, 2023 12:20

Change newsfile docs to use code-blocks

ea3aa66

(and fix typo in documented markdown start_string)

Use helpers read/write for new tests

7e27001

[pre-commit.ci] auto fixes from pre-commit.com hooks

e0af6bf

for more information, see https://pre-commit.ci

Better configuration doc formatting

d479924

Document Section Path Behaviour

fb9f6cc

Improve configuration docs re: python projects

446a723

Fix test that was altered to use dedent

4fd6453

hynek approved these changes May 4, 2023

View reviewed changes

hynek merged commit 4493cce into twisted:trunk May 4, 2023
14 checks passed

SmileyChris deleted the feature/default-markdown-template branch May 7, 2023 22:20

adiroiban mentioned this pull request Jul 7, 2023

When using towncrier create --edit, use .md or .rst #527

Closed

zecakeh mentioned this pull request Jul 12, 2023

Fix rendered changelog with new version of towncrier matrix-org/matrix-spec#1598

Merged

This was referenced Sep 15, 2023

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

Closed

use markdown default template in markdown docs #546

Merged

DMRobertson mentioned this pull request Nov 27, 2023

Tag messages don't include changelog headers matrix-org/synapse#16694

Open

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Default markdown template #483

Default markdown template #483

SmileyChris commented Mar 1, 2023 •

edited

Loading

codecov bot commented Mar 1, 2023 •

edited

Loading

hynek left a comment

hynek left a comment

hynek left a comment •

edited

Loading

SmileyChris commented May 2, 2023

SmileyChris commented May 3, 2023

hynek left a comment

hynek left a comment

Default markdown template #483

Default markdown template #483

Conversation

SmileyChris commented Mar 1, 2023 • edited Loading

Description

Changes to load.py

Better configuration docs

Reference style link support

Checklist

codecov bot commented Mar 1, 2023 • edited Loading

Codecov Report

hynek left a comment

Choose a reason for hiding this comment

hynek left a comment

Choose a reason for hiding this comment

hynek left a comment • edited Loading

Choose a reason for hiding this comment

SmileyChris commented May 2, 2023

SmileyChris commented May 3, 2023

hynek left a comment

Choose a reason for hiding this comment

hynek left a comment

Choose a reason for hiding this comment

SmileyChris commented Mar 1, 2023 •

edited

Loading

Changes to `load.py`

codecov bot commented Mar 1, 2023 •

edited

Loading

hynek left a comment •

edited

Loading