gh-115664: Merge versionchanged directives for the same version

[serhiy-storchaka]

• Issue: Fix the use of versionadded and versionchanged directives #115664

---

📚 Documentation preview 📚: https://cpython-previews--116456.org.readthedocs.build/

[barneygale]

pathlib bits look good!

[JelleZijlstra]

Why is this change necessary? If there are multiple independent changes, I think it's clearer to use two separate directives.

[serhiy-storchaka]

It is usually written in this way. If some changes use separate directives, it implies that there is a special meaning for this. Or that it is just an error.

You can more clearly see what changes were made in the same version.

[hugovk]

I think it's clearer by keeping it as-is, it makes it clear there's more than one change here -- I skim each one and decide if they're important.

With the merged one, I skim the "headline", and ignore the next one if the "headline" was less interesting.

Before

https://docs.python.org/3/library/collections.html#collections.Counter.update

After

https://cpython-previews--116456.org.readthedocs.build/en/116456/library/collections.html#collections.Counter.update

[nedbat]

It seems like the "before" is preferred to "after", at least for now. We discussed this at the May 7 Docs Working Group.

[encukou]

The other PRs on this issue are great improvements though; thank you for those!

[CAM-Gerlach]

Yup, thanks for the other changes linked to #116456 ; they all look good. I also agree that we should keep separate changes in separate versionchanged; in addition to aesthetics and conceptual consistency I'd find it confusing to skim a version changed, see something that wasn't related to my use case, skip it and then find out later that buried later in the annotation there was an unrelated, relevant change. Also, it would interfere with the still in-progress work to enhance the versionmodified directives to output structured human- and machine-readable information about additions, changes and deprecations/removals.

[serhiy-storchaka]

Thank you for your reviews. I agree, when the versionchanged directive includes several paragraphs, the formatting is unclear.

But I still think that notes about changes in function parameters could be in a single paragraph.

[erlend-aasland]

But I still think that notes about changes in function parameters could be in a single paragraph.

I agree some of those could benefit from being merged.