Add towncrier for updating the news#555
Conversation
pradyunsg
left a comment
pradyunsg
left a comment
There was a problem hiding this comment.
I'd prefer we call out new pages first, then updates and then removals.
More comments inline (reviewed on mobile, apologies for the terseness)
| showcontent = true | ||
|
|
||
| [[tool.towncrier.type]] | ||
| directory = "doc" |
There was a problem hiding this comment.
This seems unnecessary. The entire project is documentation. :)
There was a problem hiding this comment.
Ok, I can remove this type.
| underlines = ["-", "~"] | ||
|
|
||
| [[tool.towncrier.type]] | ||
| directory = "bugfix" |
There was a problem hiding this comment.
Perhaps this should instead be "Corrections" (or similar) instead?
There was a problem hiding this comment.
Is this made redundant by page updates?
There was a problem hiding this comment.
This is more for bugfixes on the backend side, not page updates.
There was a problem hiding this comment.
In that case this doesn't need to be called out on top and the current title/extension (gosh, towncrier needs more consistent naming) does not convey the same intent IMO.
| @@ -0,0 +1 @@ | |||
| Move note on PATH to --user installs section. No newline at end of file | |||
There was a problem hiding this comment.
I'd suggest adding a ".rst" to the filename, so that text editors handle the format correctly and it provides a hint of what the format is to people who write it in the future.
551.update.rst
There was a problem hiding this comment.
The only problem I have with that is towncrier looks at the file ending to name its subsections. I'll have to test out what adding .rst does to towncrier's interpretation.
There was a problem hiding this comment.
Adding .rst does not interfere, so I think this suggestion is a good one.
| showcontent = true | ||
|
|
||
| [[tool.towncrier.type]] | ||
| directory = "development" |
There was a problem hiding this comment.
What purpose would this serve?
There was a problem hiding this comment.
Do you mean why would viewers want to know about how we develop the project?
There was a problem hiding this comment.
Yep. I don't see why we'd call out internal changes out in a user-facing file.
|
This seems like a lot of overhead. What does this workflow look like for contributors? |
|
They could take a peek at current pull requests for what their number would be and include a fragment named with that number, or not change anything about the workflow and somebody else curates it at the end of each month. If the second way is closer to what you want, then I agree it's a lot of overhead just to use towncrier. |
|
With pip's use, we have a CI-like check on PRs, that exempts certain PRs from needing to create NEWS files. It makes it easier to enforce it on the PRs and most contributors just handle it themselves (there's a documentation link explaining everything). |
|
Hrm, I'm really hesitant to do this, then. Perhaps we should consider a lighter approach where we get CI to make sure each PR touches |
Hmm... That's exactly pip's approach. Did I mess up in explaining it? |
|
Oh, do you mean instead of it being a separate Heroku app for verifying the change? |
|
I'm not sure why this got closed. Is it because I referenced it in another PR that got merged? |
3 participants
Towncrier looks for a directory called "newsfragments" and uses the filenames/contents to generate a news.rst file, as requested via issue #474. News fragments should be named number.type where number is the pull request number and type is a type specified in the pyproject.toml. The most used type will probably be
.updatesince that encompasses any page updates.When running towncrier you must specify a version and date (it will look for a __version__, but there is none), and the date will end up being the title of the section, so I used
--date="Month Year". While version must be specified it is never used, and so honestly you could just say--version=1and your news will be generated all the same. If you want to see a draft without it writing to file, just include--draft.Anything in the newsfragments directory gets deleted via
git rmwhen you run towncrier, so make sure to add the fragments to git or you will have to manually delete them.Let me know if you'd like to see any changes with this PR.