Write up NEWS rules #19387

derickr · 2025-08-06T10:05:07Z

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.

Girgias · 2025-08-06T12:36:35Z

CONTRIBUTING.md

+*Bug fixes*: In the lowest supported branch, and in each newer branch, except
+for master.


This should probably clarify that master should be updated the moment alphas are tagged.

Isn't this true only for things that were introduced in master, i.e. fixed specifically for master?

Not that I am aware? I have always added bug fixes to the NEWS file in master after alpha releases so that people can know if something was fixed in alpha 2, see: eaf24ba

I have not done this, and as (I thought) I was updating current practise, I didn't add that. I always thought that we would add them in NEWS as soon as php-next was branched though.

I don't particularly care which way we decide this.

Girgias · 2025-08-06T12:39:11Z

CONTRIBUTING.md

+*Feature additions*: In master only.
+
+If for some reason a feature is introduced in a branch lower than master (this
+isn't strictly allowed), then the entry must also be in master.


Have we even done this properly for 8.5?
What about deprecations, should those also be in NEWS?

I feel the process we had at one point where NEWS was just for bug fixes and new features, deprecations, BC breaks, etc. where in UPGRADING to be way more clearer.

I was always told that NEWS is a changelog, so every observable change needs to go there.

Extreme example: if we only have new features between two alphas, and no fixes, with your rule we'd have an empty NEWS which doesn't make sense to me as there were changes.

Have we even done this properly for 8.5?

If you mean the "a feature introduced in branch lower than master", then, I'm not sure. Because I don't believe we have recently added features to the PHP-8.4 branch.

What about deprecations, should those also be in NEWS?

Deprecations also ought to be in NEWS, IMO. Like @nielsdos says, "NEWS is a changelog, so every observable change needs to go there".

But the paragraph that you replied to would currently apply to the PHP-8.4 (and earlier branches). Our policies don't allow new features in that branch, but it has happened in the past.

NEWS should contain simple line items what has been added/removed/changes, with UPGRADING describing in more detail how you would go about replacing removed/changed features.

Any new features are explicitly prohibited in the policy so this should not be here as we should never add new features. It might just bring confusion that there is a chance to add them - at least it should be this is strictly prohibited instead of this isn't strictly allowed...

iluuu1994

Could we also clarify UPGRADING, and whether new features must go into both NEWS and UPGRADING? This is still handled inconsistently. I usually only add it to UPGRADING, but some people do both.

iluuu1994 · 2025-08-06T14:48:20Z

CONTRIBUTING.md

-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.


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.

Yeah it sounds quite confusing...

iluuu1994 · 2025-08-06T14:57:20Z

CONTRIBUTING.md

+    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


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.

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.

Okay. I was unaware of that, seems rather useless. But I can adapt.

iluuu1994 · 2025-08-06T14:59:04Z

CONTRIBUTING.md

+    a non-Generator delegate crashes). (Arnaud)
+
+- OPcache:
+  . Make OPcache non-optional (Arnaud, timwolla)


Suggested change

. Make OPcache non-optional (Arnaud, timwolla)

. Make OPcache non-optional. (Arnaud, timwolla)

iluuu1994 · 2025-08-06T15:01:35Z

CONTRIBUTING.md

+*Bug fixes*: In the lowest supported branch, and in each newer branch, except
+for master.


Isn't this true only for things that were introduced in master, i.e. fixed specifically for master?

iluuu1994 · 2025-08-06T15:04:19Z

Btw, isn't this something that should live in https://github.com/php/policies/?

derickr · 2025-08-08T14:49:28Z

To answer all the other single-comment comments:

Could we also clarify UPGRADING, and whether new features must go into both NEWS and UPGRADING? This is still handled inconsistently. I usually only add it to UPGRADING, but some people do both.

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.

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.

I don't understand what you're trying to say here.

Btw, isn't this something that should live in https://github.com/php/policies/?

Maybe? It was always here, and I didn't see a reasonable location in policies for this.

iluuu1994 · 2025-08-08T17:09:07Z

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.

I don't understand what you're trying to say here.

Disregard, I wasn't aware the order-bugs-by-id rule was a thing.

CONTRIBUTING.md

bukka · 2025-08-08T17:24:32Z

CONTRIBUTING.md

+Depending on what sort of fix it is, or where in the release cycle we are,
+different NEWS files must be updated.
+
+*Security fixes*: In the lowest security-supported branch, and in each newer


There is a minor detial that from time to time some security fixes are only present in later versions.

bukka · 2025-08-08T17:30:47Z

CONTRIBUTING.md

+
+If an entry pertains a bug fix, they MUST be formatted as:
+
+    Fixed bug GH-{number} ({issue-description}). ({contributor})


It should still keep the bug tracker format as bugs are still being fixed there.

I mean in addition to the GH one, of course.

derickr force-pushed the write-up-news-rules branch 4 times, most recently from ed389b1 to 2e8ac0f Compare August 6, 2025 10:14

Write up NEWS rules

dfc7542

derickr force-pushed the write-up-news-rules branch from 2e8ac0f to 09f111e Compare August 6, 2025 10:19

Tweak commit message example to use GH issues, instead of bugsweb ones

ad25e20

derickr force-pushed the write-up-news-rules branch from 09f111e to ad25e20 Compare August 6, 2025 10:21

derickr marked this pull request as ready for review August 6, 2025 10:22

derickr requested review from bukka and iluuu1994 August 6, 2025 10:22

Girgias reviewed Aug 6, 2025

View reviewed changes

iluuu1994 reviewed Aug 6, 2025

View reviewed changes

bukka reviewed Aug 8, 2025

View reviewed changes

CONTRIBUTING.md Show resolved Hide resolved

bukka reviewed Aug 8, 2025

View reviewed changes

CONTRIBUTING.md Show resolved Hide resolved

bukka reviewed Aug 8, 2025

View reviewed changes

		Bug fixes: In the lowest supported branch, and in each newer branch, except
		for master.

	. Make OPcache non-optional (Arnaud, timwolla)
	. Make OPcache non-optional. (Arnaud, timwolla)


		If an entry pertains a bug fix, they MUST be formatted as:

		Fixed bug GH-{number} ({issue-description}). ({contributor})

Write up NEWS rules #19387

Are you sure you want to change the base?

Write up NEWS rules #19387

Uh oh!

Conversation

derickr commented Aug 6, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

nielsdos Aug 7, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

bukka Aug 8, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

iluuu1994 left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

iluuu1994 commented Aug 6, 2025

Uh oh!

derickr commented Aug 8, 2025

Uh oh!

iluuu1994 commented Aug 8, 2025

Uh oh!

Uh oh!

Uh oh!

bukka Aug 8, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

derickr commented Aug 6, 2025 •

edited

Loading

nielsdos Aug 7, 2025 •

edited

Loading

bukka Aug 8, 2025 •

edited

Loading

bukka Aug 8, 2025 •

edited

Loading