Skip to content

Commit cb6ea40

Browse files
committed
Apply review suggestions to the NEWS entry guidance
- Rename the section to "What to say" - Allow one or two sentences, not counting the attribution - Drop the pointer to What's New, so length is not the trigger - Mark the examples as preferred and not preferred with the good and bad styles
1 parent 694f8b7 commit cb6ea40

1 file changed

Lines changed: 11 additions & 11 deletions

File tree

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

Lines changed: 11 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -294,20 +294,17 @@ Readers scan it to find out whether an upgrade affects them,
294294
or to track down the change behind a new behavior.
295295
Most of them will not read the issue or the diff, so the entry must stand alone.
296296

297-
Keep it short
298-
^^^^^^^^^^^^^
297+
What to say
298+
^^^^^^^^^^^
299299

300-
A good ``NEWS`` entry is one sentence. Two is the limit.
301-
If you need more than that to describe the change,
302-
it probably also deserves a "What's New in Python" entry,
303-
where there is room to elaborate.
300+
A good ``NEWS`` entry is one or two sentences long.
304301

305302
* Start with a verb in the imperative mood that says what kind of change
306303
it is: *Fix*, *Add*, *Remove*, *Deprecate*, *Allow*, *Raise*.
307304
* Name what changed, using :ref:`inline markup <rest-inline-markup>`
308305
such as ``:func:``, ``:class:`` or ``:mod:``,
309306
so readers can jump to the documentation.
310-
* Say what a user will notice, and under which conditions.
307+
* Say what a user will notice, and under what conditions.
311308
* Stop.
312309

313310
Leave out:
@@ -321,23 +318,26 @@ Leave out:
321318
* Phrases that refer to the pull request itself, such as "this PR"
322319
or "this change".
323320

324-
Attribution is optional. If you want it, name the people who wrote
325-
the patch in a final sentence of the form ``Patch by Jane Doe.``
321+
Attribution is optional and does not count toward the length.
322+
If you want it, name the people who wrote the patch in a final sentence
323+
of the form ``Patch by Jane Doe.``
326324

327325
Examples
328326
^^^^^^^^
329327

330-
A typical entry:
328+
Preferred:
331329

332330
.. code-block:: rst
331+
:class: good
333332
334333
Fix :class:`logging.handlers.TimedRotatingFileHandler` permanently stopping
335334
rollover after a rollover failed or its backup file already existed, for
336335
example at a DST change.
337336
338-
The same change, with too much detail:
337+
Not preferred, the same change with too much detail:
339338

340339
.. code-block:: rst
340+
:class: bad
341341
342342
Fix :class:`logging.handlers.TimedRotatingFileHandler` so that it keeps
343343
rolling over after a rollover fails or finds that the backup file already

0 commit comments

Comments
 (0)