Repository navigation
More clearly document what the contents of NEWS entries should be #935
Description
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.
Activity
JelleZijlstra commentedon Aug 13, 2022
Agree that this is important to cover.
Personally, I tend to think of two audiences:
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.Lincoln-developer commentedon Nov 16, 2023
Hey, I would love to work on this if you don't mind, thanks.
Lincoln-developer commentedon Dec 5, 2023
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
erlend-aasland commentedon Dec 6, 2023
Thanks for your interest in helping out, but I already have an idea of how I want this worded :)