@@ -291,39 +291,38 @@ All ``NEWS`` entries end up being part of the changelog.
291291The changelog contains *a lot * of entries,
292292and its intended audience is mainly users, not core devs and contributors.
293293Readers 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
297297Keep it short
298298^^^^^^^^^^^^^
299299
300300A good ``NEWS `` entry is one sentence. Two is the limit.
301301If 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 ,
303303where 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
313313Leave 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
325324Attribution 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
328327Examples
329328^^^^^^^^
@@ -356,7 +355,8 @@ Format
356355
357356The contents of a ``NEWS `` file should be valid reStructuredText,
358357wrapped 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.
360360You can build HTML and verify that the link targets are appropriate
361361by using :ref: `make html <building-using-make >`.
362362
0 commit comments