Conversation
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.
psf-chronographer
Bot
added
the
bot:chronographer:provided
Documentation build overview
3 files changed± history/index.html± contributing/guidelines/index.html± pkg/cheroot.server/index.html |
Codecov Report✅ All modified and coverable lines are covered by tests. 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 |
|
@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? |
| See :file:`towncrier.toml` for all available categories | ||
| (``tool.towncrier.type``). | ||
|
|
||
| .. _Towncrier philosophy: |
There was a problem hiding this comment.
Why did you do this? I actually intentionally prefer detached references everywhere so that they are clearly labeled and can be reused.
There was a problem hiding this comment.
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.
| 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 |
There was a problem hiding this comment.
Would the link still break if you keep put it after this paragraph? 🤔
| :end-before: "## Also" | ||
| ``` | ||
|
|
||
| ## First-time setup |
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
@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?
webknjaz
left a comment
webknjaz
left a comment
There was a problem hiding this comment.
@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
2 participants
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.rstremains RST, embedded viaeval-rstinto 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
and description in grammatically correct, complete sentences
docs/) and inline docstrings reflect the changes(see [good commit messages])
(can be done once the PR number is known; alternatively, you can
use a related issue number if one exists)
[code of conduct][CoC]