Write up NEWS rules #19387
Write up NEWS rules #19387
Conversation
09f111e to
ad25e20
Compare
| When you change the NEWS file for a bug fix, then please keep the bugs sorted in | ||
| decreasing order under the fixed version. | ||
| When you change the NEWS file for a bug fix, then please keep the bugs sorted | ||
| under the fixed version. |
There was a problem hiding this comment.
IIUC, this hints at the fact that the patch notes of multiple versions live in the same NEWS file, but it makes it sound like the list itself must be ordered in some way.
| Fixed bug GH-{number} ({issue-description}). ({contributor}) | ||
|
|
||
| Bug fix entries SHOULD be clustered together, and ordered according to their | ||
| issue number. The `{issue-description}` SHOULD represent what the actual bug |
There was a problem hiding this comment.
Not that I mind, but I've never seen entries being listed by issue number, and I see no value-add for this. Usually people just append to the bottom of the list. Maybe that's what the text I previously commented on referred to.
There was a problem hiding this comment.
I think this is a rule that has been relaxed in the last decade, but we used to be very deliberate doing it this way.
There was a problem hiding this comment.
Okay. I was unaware of that, seems rather useless. But I can adapt.
|
Btw, isn't this something that should live in https://github.com/php/policies/? |
|
To answer all the other single-comment comments:
This was about NEWS, and new features should be in there. It's a full overview of what is in the release. We can tackle UPGRADING in a future patch. I can also add a section on UPGRADING. For what I understood that should contain all the information that you need for upgrading between versions. So it should document changes, deprecations (with their alternatives), etc. I don't think it needs to contain new features, but that doesn't seem to be how it is currently used.
I don't understand what you're trying to say here.
Maybe? It was always here, and I didn't see a reasonable location in policies for this. |
Disregard, I wasn't aware the order-bugs-by-id rule was a thing. |
ad25e20 to
423f7b8
Compare
|
|
||
| *Feature additions*: In master only. | ||
|
|
||
| If for some reason a feature is introduced in a branch lower than master, |
Co-authored-by: Ilija Tovilo <ilija.tovilo@me.com>
This addition documents how to update NEWS in one place, instead of it being on the wiki, here, and scattered throughout documents.
I believe that I have documented the current practise, but comments welcome.