Convert contributing docs to Markdown by julianz- · Pull Request #842 · cherrypy/cheroot

julianz- · 2026-09-19T03:03:25Z

What kind of change does this PR introduce?

What do these changes do?

Converts .github/CONTRIBUTING.md and docs/contributing/guidelines.md from RST to Markdown, using MyST-parser (added in Add MyST-Parser and link community files in docs sidebar #835) to render them.
Fixes the "Also" section so that it doesn't refer back to itself in the rendered version - it only shows up when reading CONTRIBUTING.md directly on GitHub.
Drops CONTRIBUTING.md's opening pointer to the root README, which sends readers to a file with little relevant additional information for contributors.
Updates one link in changelog-fragments.d/README.rst that broke once that file got pulled into the new Markdown page.

Are there changes in behavior for the user?

None — this only affects contributors reading the docs, not end users

Is it a substantial burden for the maintainers to support this?

No. It's a one-time format migration. Worth noting though:
changelog-fragments.d/README.rst remains RST, embedded via eval-rst
into an otherwise-Markdown page — a minor format seam, not a burden.

Related issue number

Discussed with @webknjaz in chat; not tied to a filed issue.

Checklist

Convert .github/CONTRIBUTING.md and docs/contributing/guidelines.md from RST to Markdown, using MyST-parser (added in cherrypy#835) to render them. In addition, fix the "Also" section linking the rendered guidelines page back to itself: exclude it from the include instead of just rewording it, so it only shows up when reading CONTRIBUTING.md directly on GitHub. And drop CONTRIBUTING.md's opening pointer to the root README, which sends readers to a file with little relevant additional information for contributors. Also update one link in changelog-fragments.d/README.rst that broke once that file got pulled into the new Markdown page.

read-the-docs-community · 2026-09-19T03:05:28Z

Documentation build overview

📚 cheroot | 🛠️ Build #34646978 | 📁 Comparing ac30555 against latest (407c6dc)

🔍 Preview build

3 files changed

± history/index.html
± contributing/guidelines/index.html
± pkg/cheroot.server/index.html

codecov · 2026-09-19T03:08:36Z

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 78.20%. Comparing base (407c6dc) to head (ac30555).
✅ All tests successful. No failed tests found.

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #842      +/-   ##
==========================================
+ Coverage   78.16%   78.20%   +0.04%     
==========================================
  Files          41       41              
  Lines        4791     4791              
  Branches      548      548              
==========================================
+ Hits         3745     3747       +2     
+ Misses        906      905       -1     
+ Partials      140      139       -1

webknjaz · 2026-09-21T19:18:53Z

@julianz- the CI is failing under Python 3.13+ due to a new validation check in coveragepy. Could you look into cherry-picking re-actors/alls-green@8de05dc in a standalone PR to fix the CI overall?

webknjaz · 2026-09-21T19:22:39Z

   See :file:`towncrier.toml` for all available categories
   (``tool.towncrier.type``).
-
-.. _Towncrier philosophy:


Why did you do this? I actually intentionally prefer detached references everywhere so that they are clearly labeled and can be reused.

Oh, the commit message says that one link broke. Did you mean this one?

@julianz- pro tip — you can leave additional notes right in the code review diff, as inline threads, like I do here. This helps enrich the context and saves me from having to guess.

Sorry I made you hunt for the explanation. Will try to add comments more proactively as you suggest - thanks for the tip! Yes, this is the link that broke - the Towncrier philosophy reference and its target.

I originally thought to retain as an RST file in order to keep the changes smaller and more manageable. I see you suggested changing it below though, so maybe I will do that after all. The issue with it as an RST file, is that I had to pull it into the new guidelines.md page through an {eval-rst} block wrapping the old include directive. This generates ERROR: Unknown target name: "towncrier philosophy"with detached refs no matter where I place them presumably because of the eval-rst embedding.

webknjaz · 2026-09-21T19:27:08Z

 updating to the new version of the software will affect
 end-users. This is why we enforce collection of the change
-fragment files in pull requests as per `Towncrier philosophy`_.
+fragment files in pull requests as per `Towncrier philosophy


Would the link still break if you keep put it after this paragraph? 🤔

Yes tried that and it still breaks alas!

webknjaz · 2026-09-21T19:30:14Z

+:end-before: "## Also"
+```
+
+## First-time setup


This sort of gives me vibes of a "this is how you use a computer". Wonder if this is useful at all or should link to something external. Although, I realize that a format conversion PR is not a place to discuss this. So this is just a side note for the future.

Agreed - the noob vibes would be less grating if this were a lot shorter or pointed elsewhere as you suggest!

webknjaz · 2026-09-21T19:36:38Z

@julianz- what if we updated this to be a README.md too? Would it be helpful or do you think this is out of the scope here?

See above comment. I think maybe we should do this in order to get the more complete conversion over and done with.

webknjaz

@julianz- I'll let you decide whether you want to extend the scope a little or merge this as is.

In any case, I'd like a follow-up to reconfigure Towncrier to start using MD for the fragment files to make people's lives easier. This will require some amount of integration work, though. Here's a few places to pick up a few cool tricks from: https://github.com/jazzband/pip-tools/pull/2203/changes#diff-e010bb4b0f729415605939bacb0af8800a91a06d404da48b7e3fac5a74cddc90 / https://github.com/jazzband/pip-tools/pull/2343/changes#diff-e010bb4b0f729415605939bacb0af8800a91a06d404da48b7e3fac5a74cddc90R19

psf-chronographer Bot added the bot:chronographer:provided A mark meaning that a new change log entry is present within the patch. label Sep 19, 2026

webknjaz reviewed Sep 21, 2026

View reviewed changes

webknjaz approved these changes Sep 21, 2026

View reviewed changes

Uh oh!

Conversation

julianz- commented Sep 19, 2026

What kind of change does this PR introduce?

What do these changes do?

Are there changes in behavior for the user?

Is it a substantial burden for the maintainers to support this?

Related issue number

Checklist

Uh oh!

read-the-docs-community Bot commented Sep 19, 2026

Documentation build overview

Uh oh!

codecov Bot commented Sep 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

webknjaz commented Sep 21, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

julianz- Sep 22, 2026 • 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!

webknjaz left a comment

Choose a reason for hiding this comment

Uh oh!

This branch has not been deployed

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

codecov Bot commented Sep 19, 2026 •

edited

Loading

julianz- Sep 22, 2026 •

edited

Loading