Repository navigation
More clearly document what the contents of NEWS entries should be #935
Description
Activity
Agree that this is important to cover.
Personally, I tend to think of two audiences:
- A user who is looking to upgrade, and wants to know what changed in the version they're about to upgrade to.
- A user who is seeing some issue after performing an upgrade, and wants to track down what caused it. They might search the changelog for some keywords.
Though I find that personally I wouldn't use NEWS entries for this. In the first case I'd just look at the What's New document; in the second case I would be more likely to check
git logfor the affected module.Reacted by Erlend E. AaslandHey, I would love to work on this if you don't mind, thanks.
Well l also agree with this suggestion to mention what a NEWS entry is as suggested by @erlend-aasland , personally l have experienced this ,some time back when l started my contributions l had to include a NEWS entry but one challenge l faced was that the devguide only explicitly shows how a NEWS entry is implemented and does not mention anything concerning what it is and its contents and this makes someone just starting out kinder not understand what exactly it is. In this case as l embark working on this issue, my suggestion is how about if we kinder include the "what is the NEWS entry" and also persist "the how it is implemented". In this case I feel its gonna be more strong mentioning what a NEWS entry is and how it is implemented, kindly l hope to get feed back on this, otherwise l am taking the earlier suggestion by @erlend-aasland for implementation. Thanks
Hey, I would love to work on this if you don't mind, thanks.
Thanks for your interest in helping out, but I already have an idea of how I want this worded :)
Reacted by Angufibo Lincoln- linked a pull request that will close this issueRework the docs for NEWS/What's New entries #1238
on Dec 6, 2023
The devguide describes in great detail how and when to write NEWS entries (reST syntax, line length, using blurb, etc.), but it barely touches on the subject of what the NEWS entry should contain. IMO we should prioritise telling what a NEWS entry is, rather than how to write it.
https://devguide.python.org/core-developers/committing/?highlight=news%20entry#updating-news-and-what-s-new-in-python