Skip to content

Write up NEWS rules #19387

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 2 commits into
base: master
Choose a base branch
from
+84 −9
Open

Write up NEWS rules #19387

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
dfc7542
Write up NEWS rules
derickr Aug 6, 2025
ad25e20
Tweak commit message example to use GH issues, instead of bugsweb ones
derickr Aug 6, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
93 changes: 84 additions & 9 deletions CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -26,6 +26,7 @@ had several contributions accepted, commit privileges are often quickly granted.
* [What happens when your contribution is applied?](#what-happens-when-your-contribution-is-applied)
* [Git commit rules](#git-commit-rules)
* [Copyright and license headers](#copyright-and-license-headers)
* [NEWS file](#news)

## Pull requests

Expand Down Expand Up @@ -385,11 +386,8 @@ The next few rules are more of a technical nature:
later branches) an empty merge should be done.

2. All news updates intended for public viewing, such as new features, bug
fixes, improvements, etc., should go into the NEWS file of *any stable
release* version with the given change. In other words, news about a bug fix
which went into PHP-5.4, PHP-5.5 and master should be noted in both
PHP-5.4/NEWS and PHP-5.5/NEWS but not master, which is not a public released
version yet.
fixes, improvements, etc., should go into the NEWS file. See the section on
[NEWS](#news) below.

3. Do not commit multiple files and dump all messages in one commit. If you
modified several unrelated files, commit each group separately and provide a
Expand Down Expand Up @@ -422,14 +420,13 @@ An Example from the git project (commit 2b34e486bc):
'arg' variable no longer is available.

If you fix some bugs, you should note the bug ID numbers in your commit message.
Bug ID should be prefixed by `#`.

Example:

Fixed bug #14016 (pgsql notice handler double free crash bug.)
Fixed GH-14009: Fix prototype for trait method.

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.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yeah it sounds quite confusing...


## Copyright and license headers

Expand All @@ -453,4 +450,82 @@ New source code files should include the following header block:
*/
```

## NEWS

The purpose of the NEWS file is to record all the changes that are relevant for
users and developers alike. These could be bug fixes, feature additions, syntax
additions, or deprecations.

### Format

Each PHP version has a section, starting with the format:

{DD} {MMM} {YYY}, PHP {version}

Such as:

06 Jun 2024, PHP 8.1.29

In each section, entries are ordered by their extension. Extensions are listed
alphabetically, with the exception of "Core", which MUST be listed first. Each
extension's section starts with: `- {name}:\n`

For each extension, entries are indented by two spaces, followed by `. ` (a
period and a space).

Entries MUST start with a capital and end with a period (`.`). The period goes
outside of the `{issue-description}`.

Each entry SHOULD be followed by the name of the contributor, or their GitHub
handle if they so choose.
Comment on lines +479 to +480
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

FWIW: I've always used the lowercased php.net account name if one exists and the real name otherwise.


Entries MUST be wrapped at 80 characters.

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

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

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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


Bug fix entries SHOULD be clustered together, and ordered according to their
issue number. The `{issue-description}` SHOULD represent what the actual bug
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

fix is about, and not necessarily what the user reported. Edit the description
in the GitHub ticket to match.

An example:

```
31 Jul 2025, PHP 8.5.0alpha4

- Core:
. Added PHP_BUILD_PROVIDER constant. (timwolla)
. Fixed bug GH-16665 (\array and \callable should not be usable in
class_alias). (nielsdos)
. Fixed bug GH-19326 (Calling Generator::throw() on a running generator with
a non-Generator delegate crashes). (Arnaud)

- OPcache:
. Make OPcache non-optional (Arnaud, timwolla)
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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


- OpenSSL:
. Add $digest_algo parameter to openssl_public_encrypt() and
openssl_private_decrypt() functions. (Jakub Zelenka)
```

### Branches

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
Copy link
Member

@bukka bukka Aug 8, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

branch, except for master.

*Bug fixes*: In the lowest supported branch, and in each newer branch, except
for master.
Comment on lines +521 to +522
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.


*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.
Comment on lines +524 to +527
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Member

@nielsdos nielsdos Aug 7, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Member

@bukka bukka Aug 8, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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


## Thanks

Thank you for contributing to PHP!