Skip to content

Commit cdf7387

Browse files
committed
Fix contradictions in the NEWS entry guidance
A What's New entry is added in addition to the NEWS entry, not instead of it. Attribution may name whoever wrote the patch, not only the person writing the entry. Soften the claim that readers never follow the issue link, since the example text relies on it. Use literals for the role names, since the rst:role references do not resolve in this build.
1 parent fca86c1 commit cdf7387

1 file changed

Lines changed: 16 additions & 16 deletions

File tree

‎getting-started/pull-request-lifecycle.rst‎

Lines changed: 16 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -291,39 +291,38 @@ All ``NEWS`` entries end up being part of the changelog.
291291
The changelog contains *a lot* of entries,
292292
and its intended audience is mainly users, not core devs and contributors.
293293
Readers scan it to find out whether an upgrade affects them,
294-
or to track down the change behind a new behaviour.
295-
They will not read the issue or the diff, so the entry must stand alone.
294+
or to track down the change behind a new behavior.
295+
Most of them will not read the issue or the diff, so the entry must stand alone.
296296

297297
Keep it short
298298
^^^^^^^^^^^^^
299299

300300
A good ``NEWS`` entry is one sentence. Two is the limit.
301301
If you need more than that to describe the change,
302-
it is probably a candidate for "What's New in Python" instead,
302+
it probably also deserves a "What's New in Python" entry,
303303
where there is room to elaborate.
304304

305305
* Start with a verb in the imperative mood that says what kind of change
306306
it is: *Fix*, *Add*, *Remove*, *Deprecate*, *Allow*, *Raise*.
307307
* Name what changed, using :ref:`inline markup <rest-inline-markup>`
308-
such as :rst:role:`:func: <py:func>`, :rst:role:`:class: <py:class>`
309-
or :rst:role:`:mod: <py:mod>`, so readers can jump to the documentation.
308+
such as ``:func:``, ``:class:`` or ``:mod:``,
309+
so readers can jump to the documentation.
310310
* Say what a user will notice, and under which conditions.
311311
* Stop.
312312

313313
Leave out:
314314

315-
* the issue or pull request number (it is already in the file name)
316-
* implementation details and the root cause of a bug
317-
* what happened before the change, if the fix already implies it
318-
* how the problem was found, or who reported it
319-
* tests that were added or changed
320-
* benchmark figures, unless the change is a performance improvement
321-
* filler such as "improves robustness" or "makes the code cleaner"
322-
* phrases that refer to the pull request itself, such as "this PR"
323-
or "this change"
315+
* Implementation details and the root cause of a bug.
316+
* What happened before the change, if the fix already implies it.
317+
* How the problem was found, or who reported it.
318+
* Tests that were added or changed.
319+
* Benchmark figures, unless the change is a performance improvement.
320+
* Filler such as "improves robustness" or "makes the code cleaner".
321+
* Phrases that refer to the pull request itself, such as "this PR"
322+
or "this change".
324323

325324
Attribution is optional. If you want it, add it as a final sentence
326-
in the form ``Patch by Your Name.`` and name only yourself.
325+
in the form ``Patch by Jane Doe.`` naming the people who wrote the patch.
327326

328327
Examples
329328
^^^^^^^^
@@ -356,7 +355,8 @@ Format
356355

357356
The contents of a ``NEWS`` file should be valid reStructuredText,
358357
wrapped at 80 characters. There is no indentation or leading marker in the
359-
file (for example, ``-``), and no need to start with the issue number.
358+
file (for example, ``-``), and no need to start with the issue number,
359+
since it is already part of the file name.
360360
You can build HTML and verify that the link targets are appropriate
361361
by using :ref:`make html <building-using-make>`.
362362

0 commit comments

Comments
 (0)