STYLE sort whatsnew entries alphabeticaly, allow for trailing full stops

[MarcoGorelli]

This came up in #52214 - cc @rhshadrach

[phofl]

The sorting become bothersome while fixing regressions. It blocks more or less every pr of mine. Not sure what others think about it

cc @mroeschke @jbrockmendel

[jbrockmendel]

maybe it is more troublesome on backport PRs that tend to have very-recent issue numbers? i haven't found it to be a pain point in general (nor have i found it to significantly decrease merge conflicts which IIRC was a big motivator)

[phofl]

Yeah probably, but we didn't get many merge conflicts in the 1.x release notes anyway and the 1.x.y notes tend to be ordered because we are fixing bugs as they come in if possible

[rhshadrach]

Thanks @MarcoGorelli - I'm guessing we'll be chasing some ill formatting every once in a while but I'm still positive on seeing how this goes.

The sorting become bothersome while fixing regressions. It blocks more or less every pr of mine.

Is the sorting making things worse, or is it just not helping?

[mroeschke]

I think lately as there are more PRs addressing 2.0.x regressions, multiple open PRs have their whatsnew entry at the end of a section due to the hook, then when one is merged the others have merge conflicts

[MarcoGorelli]

I think the issue with backports is the 2.0.x branch doesn't have this hook

One simple solution could be to just add this hook to the 2.0.x branch, which should address the problem (thanks for having brought this up! It was meant to help, and if it's not doing that, then that's an issue). @phofl any objections to that?

[phofl]

The main problem are the conflicts when merging into main, the actual backports aren’t a problem right now since we can’t merge more than one pr anyway before we have to rebase

[MarcoGorelli]

I don't follow - if it happens when merging to main, when why do you mention regressions? Wouldn't that happen for any PR (regression or not)?

I'm surprised anyway - could you please tag me in a PR next time it happens please? Hoping this is salvageable

[phofl]

As @mroeschke said, we are fixing the regressions as they come in, which means that all the whatsnews are at the end of one section, e.g. if you merge a pr all other prs that would add a note to the end of the section are blocked.

#52577

This one got blocked by another pr that was merged tonight. The same happens for most prs that target 2.0.1

[MarcoGorelli]

thanks

which means that all the whatsnews are at the end of one section

Isn't this what we always used to do before the script anyway? How does the script affect it? Where would you have put the whatsnew entry if the script wasn't there?

[phofl]

I would have alternated between the beginning, end and somewhere in the middle. This works in 99% of the cases as soon as we have a couple of notes

[MarcoGorelli]

ah, I see. yeah if you were already putting the entry a bit at random, then the script would indeed make things worse. I thought everyone was always adding entries to the end

🤔 maybe there's another ordering we can use, which would:

• not force regressions whatsnews entries to all be piled up at the end
• prevent everyone from adding whatsnews entries to the end (which is what used to cause all the conflicts)

[MarcoGorelli]

How about if we sort alphabetically? I'd expect this to solve the issues, and whatsnew conflicts are pretty common

Else I don't mind removing it, I'm not that attached to it

[phofl]

I don't know, I barely had conflicts before we introduced the sorting (only when whatsnew was basically empty, but this can't be solved by any sorting mechanism).

[MarcoGorelli]

I barely had conflicts before we introduced the sorting

is this because you would insert whatsnew entries in random places, rather than always at the end (like most people seem to)? because I do see it come up a fair bit, and have heard so from others too

[phofl]

Yeah I almost never insert at the end

[rhshadrach]

lgtm, except for - ironically - the whatsnew conflicts 😆

[MarcoGorelli]

😄

have fixed up, with:

 2005  git merge upstream/main
 2006  git checkout upstream/main -- doc/source/
 2007  pre-commit run sort-whatsnew-items -a
 2008  git add -u
 2009  git merge --continue
 2010  git push origin HEAD

OK to merge before other conflicts creep in?

Thanks all for your patience here, if this works I'm confident it'll help in the long-run

[mroeschke]

Thanks @MarcoGorelli

Mind manually creating a PR against the 2.0.x branch adjusting v2.0.1.rst whatsnew to how it's structured here?

[MarcoGorelli]

yup, doing it now