Documentation: short change list?

[wavexx]

matplotlib has a nice convention of keeping track of user-visible changes, by requiring to append a very short summary to a whats_new/[file] directory. These files are cat-ed together for a final developer-friently changelog.

I really like the idea a lot. Since I'm following the master branch, there are just too many changes to follow by looking at the commit log. I'd like to have just a summary of user visible changes, such as new interfaces, new APIs, etc.

To give an example, see PR #7616. It would be nice to have just a line saying "host count is now supported in the machine file". If I'm interested, I could just blame the changelog and see the relevant commit for full details.

Nothing fancy; just something that takes seconds and adds convenience for developers.

The mpl approach to generate a nice-looking whats_new is also a bit overkill at this stage. Just a bullet list in a text file would be good.

[timholy]

You mean, something like NEWS.md?

[wavexx]

Ha, yes ;).

Then maybe I should have updated NEWS.md for that particular PR?

[timholy]

Sure, that would be great.

[wavexx]

Ok then, sorry for the noise. I'll file a separate PR.
Maybe maintainers should promote NEWS more actively when relevant?
I know mpl guys enforce this when the changes are relevant.

[ivarne]

A new PR with NEWS.md notes for #7616 would be great indeed.

We definitely should be more careful to promote lots of things. We have come a long way though, because previously we have accepted PRs with new functions that were both undocumented and without tests. That won't happen anymore.

I'm closing this now, because (I think) we have clarified everything needed here.