This resolves #11861 (A confusion caused by incorrect information in the release notes).
More information can be found at #11861.
Do we fix release notes?
I would imagine the intent of release notes is to support a release, by providing accurate information about it. So, my opinion would be that we should. Happy to hear arguments against :).
Normally I'm against changing release notes after a release. They have been copied to many places, in mail, other sites. So it's like closing the barn after the horse left.
But I'm okay with changing this as the examples are really wrong. I'm surprised no one discovered this sooner.
I'm surprised no one discovered this sooner.
Heh, I'm not surprised by this at all. While we were discussing this change (admittedly, I was against it), I asked repeatedly for documentation to be written to accompany it because I thought the usage was complex and confusing.
I think it's best when documentation and code changes are made at the same time. It prevents mistakes, makes code easier to review, and can even lead to better designs because often writing documentation causes you to look at things from a different perspective.