Skip to content
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.

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

WIP: start writing migration guide #3822

Merged
merged 35 commits into from
Oct 16, 2024
Merged

Conversation

Girgias
Copy link
Member

@Girgias Girgias commented Oct 2, 2024

TODO:

UPGRADING Sections:

  • Section 1: BC Breaks (into incompatibilities.xml)
  • Section 2: New features (into new-features.xml)
  • Section 4: Deprecations (into deprecated.xml)
  • Section 6: New functions (into new-functions.xml)
  • Section 7: New classes & interfaces (into new-classes.xml)
  • Add all the PDO driver subclasses to the New Class page (and update UPGRADING)

@Girgias Girgias force-pushed the 8.4-migration-guide branch 3 times, most recently from fb35efa to d4bc815 Compare October 2, 2024 18:46
@Girgias
Copy link
Member Author

Girgias commented Oct 2, 2024

@cmb69 Do you think it makes sense to add a new dedicated page for new class constants? Because at the moment it is all over the place in the UPGRADING document....

Covers section 12 of UPGRADING
This should cover sections 3, 5, 9, 13, and 14 of UPGRADING
Cover section 8 of UPGRADING
Covers section 7 of UPGRADING
@cmb69
Copy link
Member

cmb69 commented Oct 3, 2024

Do you think it makes sense to add a new dedicated page for new class constants? Because at the moment it is all over the place in the UPGRADING document....

Yeah, not sure. Userland developers likely want to ignore some of the extensions, and may not even be interested in new class constants per se, but rather how they fit into a new feature. So the current structure makes some sense.

Maybe make a list of the new constants while writing the pages, and then post it somewhere, so they can be documented right away (I know, more work for when writing the migration guide, and if nobody documents the constants, it not of much help.)

@Girgias
Copy link
Member Author

Girgias commented Oct 3, 2024

Do you think it makes sense to add a new dedicated page for new class constants? Because at the moment it is all over the place in the UPGRADING document....

Yeah, not sure. Userland developers likely want to ignore some of the extensions, and may not even be interested in new class constants per se, but rather how they fit into a new feature. So the current structure makes some sense.

Maybe make a list of the new constants while writing the pages, and then post it somewhere, so they can be documented right away (I know, more work for when writing the migration guide, and if nobody documents the constants, it not of much help.)

Right, maybe we just need to reorganize how the UPGRADING document is structured, or split the "other changes" page into more distinct ones for functions, classes, and generic extension behaviour.

This covers section 6 of UPGRADING
Copy link
Member

@cmb69 cmb69 left a comment

Choose a reason for hiding this comment

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

Thank you very much for tackling this huge task! I left a couple of comments below.

I'm not sure how you/we handle updates to UPGRADING. Is it better to mention these here explicitly, or will a second check of UPGRADING be done?

appendices/migration84/constants.xml Outdated Show resolved Hide resolved
appendices/migration84/new-classes.xml Outdated Show resolved Hide resolved
appendices/migration84/removed-extensions.xml Outdated Show resolved Hide resolved
appendices/migration84/windows-support.xml Show resolved Hide resolved
@Girgias
Copy link
Member Author

Girgias commented Oct 5, 2024

I'm not sure how you/we handle updates to UPGRADING. Is it better to mention these here explicitly, or will a second check of UPGRADING be done?

Better to ping this PR just to be sure.
Especially as we sometimes reorganise how the migration looks compared to UPGRADING.

@cmb69
Copy link
Member

cmb69 commented Oct 5, 2024

Better to ping this PR just to be sure.

php/php-src@820037d

@Girgias
Copy link
Member Author

Girgias commented Oct 5, 2024

Better to ping this PR just to be sure.

php/php-src@820037d

Yep that is in the guide as I refreshed UPGRADING before writing that section. :)

Copy link
Member

@TimWolla TimWolla left a comment

Choose a reason for hiding this comment

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

Some first remarks. Didn't look at every file yet.

<function>curl_multi_select</function> now throws a
<exceptionname>ValueError</exceptionname> if the
<parameter>timeout</parameter> parameter is less than
<literal>0</literal> or greater than <constant>PHP_INT_MAX</constant>.
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
<literal>0</literal> or greater than <constant>PHP_INT_MAX</constant>.
<literal>0</literal> or greater than <literal>2147483647</literal>.

The range is a C int, which is 32 bits on all platforms I am aware of.

Copy link
Member

Choose a reason for hiding this comment

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

It seems neither is correct, see https://github.com/php/php-src/pull/15594/files. Would need to be fixed in UPGRADING, too.

Comment on lines +216 to +217
to be consistent with the new
<constant>PHP_ROUND_<replaceable>*</replaceable></constant> modes.
Copy link
Member

Choose a reason for hiding this comment

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

These new mode constants do not exist: They have been replaced by the RoundingMode enum.

Copy link
Member

Choose a reason for hiding this comment

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

Needs a fix in UPGRADING.

appendices/migration84/other-changes.xml Outdated Show resolved Hide resolved

<simpara>
It is now possible to fetch the value of the
<!-- TODO Is this a class constant of the driver class? -->
Copy link
Member

Choose a reason for hiding this comment

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

I believe it might even be a class constant on PDO by accident.

Copy link
Member

Choose a reason for hiding this comment

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

The FB_ATTR_* are there for historic/BC reasons; we still have a lot more https://heap.space/search?project=PHP-8.4&full=&defs=&refs=REGISTER_PDO_CLASS_CONST_LONG&path=&hist=&type=.

appendices/migration84/other-changes.xml Outdated Show resolved Hide resolved
appendices/migration84/other-changes.xml Outdated Show resolved Hide resolved
appendices/migration84/other-changes.xml Outdated Show resolved Hide resolved
appendices/migration84/other-changes.xml Outdated Show resolved Hide resolved
<constant>FB_ATTR_TIME_FORMAT</constant>,
<constant>FB_ATTR_TIMESTAMP_FORMAT</constant>,
attributes with
<!-- TODO Only for the specific driver class? -->
Copy link
Member

Choose a reason for hiding this comment

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

Well, yes, unless the attribute values overlap. There are however, new constants on Pdo\Firebird, see https://github.com/php/php-src/blob/PHP-8.4/ext/pdo_firebird/pdo_firebird.stub.php.

appendices/migration84/constants.xml Outdated Show resolved Hide resolved
appendices/migration84/constants.xml Outdated Show resolved Hide resolved
appendices/migration84/incompatible.xml Outdated Show resolved Hide resolved
appendices/migration84/incompatible.xml Outdated Show resolved Hide resolved
appendices/migration84/incompatible.xml Outdated Show resolved Hide resolved
appendices/migration84/new-features.xml Show resolved Hide resolved
appendices/migration84/other-changes.xml Outdated Show resolved Hide resolved
appendices/migration84/other-changes.xml Outdated Show resolved Hide resolved
appendices/migration84/other-changes.xml Outdated Show resolved Hide resolved
appendices/migration84/removed-extensions.xml Outdated Show resolved Hide resolved
@Girgias
Copy link
Member Author

Girgias commented Oct 16, 2024

I might merge the PR as it currently is, this will not show-up online yet until doc-base is updated to include the new appendix

Copy link
Member

@cmb69 cmb69 left a comment

Choose a reason for hiding this comment

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

Wow, an awesome amount of good work! Thank you!

A couple of nits below, but generally this looks good to be merged.

appendices/migration84/deprecated.xml Outdated Show resolved Hide resolved
appendices/migration84/incompatible.xml Outdated Show resolved Hide resolved
appendices/migration84/incompatible.xml Outdated Show resolved Hide resolved
appendices/migration84/incompatible.xml Outdated Show resolved Hide resolved
appendices/migration84/incompatible.xml Outdated Show resolved Hide resolved
appendices/migration84/incompatible.xml Outdated Show resolved Hide resolved
appendices/migration84/incompatible.xml Outdated Show resolved Hide resolved
Girgias and others added 2 commits October 16, 2024 11:42
Co-authored-by: Christoph M. Becker <[email protected]>
@Girgias Girgias merged commit d64e811 into php:master Oct 16, 2024
2 checks passed
@Girgias Girgias deleted the 8.4-migration-guide branch October 16, 2024 10:45
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

8 participants