On 18.05.2018 10:55, Serhiy Storchaka wrote:
17.05.18 21:39, Brett Cannon пише:
Maybe we should start thinking about flagging PRs or issues as
needing a What's New entry to help track when they need one, or
always expect it in a PR and ignore that requirement when a 'skip
whats new' label is applied. That would at least make it easier to
keep track of what needs to be done.
The requirement of flagging PRs or issues as needing a What's New
entry doesn't differ in principle from the requirement of creating a
What's New entry for these changes. The latter is good, and I'm trying
always create a What's New entry for significant enhancement or
potentially breaking change. And even I sometimes is unsure and don't
document some important changes (like in issue30399). Needed a look of
yet one pair of eyes.
As for requiring a What's New entry by default and introducing a 'skip
whats new' label, I suppose this will add much nuisance. Most PRs
(except docs and tests changes) need a news entry, but most PRs don't
need a What's New entry because their are bug fixes. Therefore a 'skip
whats new' label will be required much more times than 'skip news' or
'skip issue' labels.
Since Python uses semantic versioning (https://semver.org), the
criterion for "what's new-worthy" changes is simple: they are _public
interface changes_ (which include visible changes to documented behavior).
(I maintain that changes to behavior that is not documented -- incl.
issue30399 -- are _not_ public interface changes, and whoever relies on
them does that on their own risk.)
Reading previous What's New, I see that it is structured like this
* Entries for major changes:
* General design decisions
* Changes that fall into a category (more recent What's New's
include about a dozen categories)
* "Other": the list of the rest
So, it makes sense to mark work items as "interface change" or
something, and optionally with a caterory if that category is established.
You can't make a mistake here 'cuz a public interface change requires an
edit to related documentation.
A thing that can help is a tool that makes a structural diff between
NEWS files for different versions and between different branches. It
will filter out bugfix changes. The simple 'diff' is not well
appropriate because entries can be in different order, and news
entries now are scattered between several files, and news entries for
previous version sometimes should be searched in different files, and
sometimes should be searched on a different branch. The text of
entries in different versions can also be different because the same
issue can change the behavior on the master and backport the part of
changes as a bugfix.
Not all bugs apply to all, or multiple branches, so that wouldn't filter
them out reliably.
_______________________________________________
Python-Dev mailing list
Python-Dev@python.org
https://mail.python.org/mailman/listinfo/python-dev
Unsubscribe:
https://mail.python.org/mailman/options/python-dev/vano%40mail.mipt.ru
--
Regards,
Ivan
_______________________________________________
Python-Dev mailing list
Python-Dev@python.org
https://mail.python.org/mailman/listinfo/python-dev
Unsubscribe:
https://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
