#706 Refactor markdown template to make it easier to read by OnceUponALoop · Pull Request #709 · twisted/towncrier

OnceUponALoop · 2025-05-23T02:09:41Z

Description

Template

Update the default markdown template to use standard jinja formatting

improve logical flow
add indentation
add comments for easier parsing
generally made it easier to understand, extend, and customize.

Fixes #706

CI

ci: add --yes flag to build tests to prevent interactive prompt failures
ci: fix clirunner
- Adapt CliRunner for different Click library versions to correctly handle error messages.
chore: define gitattributes for templates
- allows github to display them with the right syntax highlighting

Checklist

Make sure changes are covered by existing or new tests.
For at least one Python version, make sure test pass on your local environment.
Create a file in src/towncrier/newsfragments/. Briefly describe your
changes, with information useful to end users. 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 CLI arguments (or change the meaning of existing ones), make sure docs/cli.rst reflects those changes.
If you add new configuration options (or change the meaning of existing ones), make sure docs/configuration.rst reflects those changes.

- improve logical flow - add indentation - detailed comments - generally made it easier to understand, extend, and customize.

- Adapt CliRunner for different Click library versions to correctly handle error messages.

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

OnceUponALoop · 2025-05-23T02:29:57Z

Not sure if this is something you'd want to do on a project level but I wanted to silence the encoding warnings to be able to parse the output

diff --git a/noxfile.py b/noxfile.py
index 494085c..92d6359 100644
--- a/noxfile.py
+++ b/noxfile.py
@@ -21,6 +21,7 @@ def pre_commit(session: nox.Session) -> None:
 @nox.session(python=["pypy3.10", "3.9", "3.10", "3.11", "3.12", "3.13"])
 def tests(session: nox.Session) -> None:
     session.env["PYTHONWARNDEFAULTENCODING"] = "1"
+    session.env['PYTHONWARNINGS'] = 'ignore::EncodingWarning'
     session.install("Twisted", "coverage[toml]")
     posargs = list(session.posargs)

- allows github to display them with the right syntax highlighting

adiroiban · 2025-05-23T11:45:34Z

Not sure if this is something you'd want to do on a project level but I wanted to silence the encoding warnings to be able to parse the output

I think that the idea with the encoding warnings was to observer which code triggered the warnings and fix the code.

Are these warnings from dependencies ? Maybe we can send fixes upstream

adiroiban

All good. Great work. Thanks. Only minor comments.

The PR description contains notes about the changes, but I prefer to have those notes in the code... to have them available for future reads of those files

adiroiban · 2025-05-23T10:57:16Z

        )

-        result = runner.invoke(_main, ["--date", "01-01-2001"], catch_exceptions=False)
+        result = runner.invoke(


just asking? Why do we need --yes here ... and why it wasn't required in the previous version of the code?

if not you get the following test failures

Example:

towncrier.test.test_build.TestCli.test_markdown_no_name_title =============================================================================== [FAIL] Traceback (most recent call last): File "/home/runner/work/towncrier/towncrier/.nox/tests-3-10/lib/python3.10/site-packages/towncrier/test/helpers.py", line 96, in test return fn(*args, runner=runner, **kw) File "/home/runner/work/towncrier/towncrier/.nox/tests-3-10/lib/python3.10/site-packages/towncrier/test/test_build.py", line 1797, in test_showcontent_default_toml_array self.assertEqual(0, result.exit_code, result.output) File "/home/runner/work/towncrier/towncrier/.nox/tests-3-10/lib/python3.10/site-packages/twisted/trial/_synctest.py", line 444, in assertEqual super().assertEqual(first, second, msg) File "/opt/hostedtoolcache/Python/3.10.17/x64/lib/python3.10/unittest/case.py", line 845, in assertEqual assertion_func(first, second, msg=msg) File "/opt/hostedtoolcache/Python/3.10.17/x64/lib/python3.10/unittest/case.py", line 838, in _baseAssertEqual raise self.failureException(msg) twisted.trial.unittest.FailTest: 0 != 1 : Loading template... Finding news fragments... Rendering news fragments... Writing to newsfile... Staging newsfile... I want to remove the following files: /tmp/tmpm09_krm5/foo/newsfragments/+new_feature.feature.md Is it okay if I remove those files? [Y/n]:Aborted!

Did you need me to do anything more to close this out?

adiroiban · 2025-05-23T10:59:01Z

+        try:
+            runner = CliRunner(mix_stderr=False)
+        except TypeError:
+            # Fallback for older Click versions (or unexpected signature)


Which version of Click is targeted were ?

If we plan to support an older version of click we should add an explicit test run using that version of Click

I think that we should declare a minimum version of click

towncrier/pyproject.toml

Lines 31 to 33 in 2707779

requires-python = ">=3.9"

dependencies = [

"click",

I think that the idea was that towncrier is a dev tool, so users will always run it in a separte environment and will be able to use latest deps

Somehow, it looks like our code coverage checks have not failed here...as we don't report coverage for the test code itself ...

But I think that we should.... but in a separate ticket.

Click 8.2 removed the mix_stderr option - see Click Changelog

This results in the following test failures

Example:

towncrier.test.test_build.TestCli.test_showcontent_default_toml_array =============================================================================== Error: Traceback (most recent call last): File "/home/runner/work/towncrier/towncrier/.nox/tests-3-10/lib/python3.10/site-packages/towncrier/test/test_check.py", line 302, in test_none_stdout_encoding_works runner = CliRunner(mix_stderr=False) builtins.TypeError: CliRunner.__init__() got an unexpected keyword argument 'mix_stderr'

I thought handling it this way would give you the most flexibility

Thanks. I think that we need to define a minimum vesion of click that we support and make sure that we execute tests using that version.

but it can be done for a separate ticket. I have created #710

I wasn't clear if this is something you wanted me to do now or define for future dev?

This is for future

Co-authored-by: Firas AlShafei <[email protected]>

adiroiban · 2025-05-29T10:03:04Z

Sorry for the delay. I have merged this now. Thanks!

OnceUponALoop and others added 4 commits May 22, 2025 21:06

refactor: markdown template

afd4039

- improve logical flow - add indentation - detailed comments - generally made it easier to understand, extend, and customize.

ci: fix clirunner

2fee0e7

- Adapt CliRunner for different Click library versions to correctly handle error messages.

ci: add --yes flag to build tests to prevent interactive prompt failures

de71f13

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

6cb9114

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

OnceUponALoop marked this pull request as ready for review May 23, 2025 02:26

OnceUponALoop requested a review from a team as a code owner May 23, 2025 02:26

chore: define gitattributes for templates

2707779

- allows github to display them with the right syntax highlighting

OnceUponALoop mentioned this pull request May 23, 2025

Easier template format #706

Closed

Show in CI logs which files are part of the code coverage report

0eeca14

adiroiban approved these changes May 23, 2025

View reviewed changes

adiroiban changed the title ~~refactor: markdown template~~ #706 Refactor markdown template to make it easier to read May 23, 2025

Apply suggestions from code review

d5cf5c7

Co-authored-by: Firas AlShafei <[email protected]>

adiroiban merged commit 3f74d9e into twisted:trunk May 29, 2025
16 checks passed

Conversation

OnceUponALoop commented May 23, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Template

CI

Checklist

Uh oh!

OnceUponALoop commented May 23, 2025

Uh oh!

adiroiban commented May 23, 2025

Uh oh!

adiroiban left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

adiroiban commented May 29, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

OnceUponALoop commented May 23, 2025 •

edited

Loading

adiroiban left a comment •

edited

Loading