devguide
devguide copied to clipboard
python
More clearly document what the contents of NEWS entries should be
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.
- Audience: Who are we writing for? This affects the detail level, and the tone of the text. This varies depending on NEWS category.
- Don't be verbose: NEWS entries are a part of a very long changelog. IMO, we should promote brevity.
- NEWS entries should communicate the actual change accurately in a way readers of the changelog will understand.
- NEWS entries should be stand-alone; they should not be dependent on the actual diff when it comes to describing the change.
https://devguide.python.org/core-developers/committing/?highlight=news%20entry#updating-news-and-what-s-new-in-python
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 log for the affected module.
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 :)