Planning for Version 2.0

markrogoyski commented 4 years ago

To keep moving forward and have smaller milestones for releases, here is what I'm considering for MathPHP v2.0 which will be the first backwards incompatible release.

Key Changes

Support PHP 7.2 as a minimum version
Improvements to the code base using PHP 7.1 and 7.2 features
Support PHPUnit 8.0
Put PHP functions in qualified root namespace (Issue 367)

As these changes are being implemented, continue to add new math features. Version 2.0 will not be dependent on any particular new math functionality.

After the release of v2.0, the v1.0 branch will only get bug fixes.

Reasons for Changes

PHP 7.2 is currently the lowest officially supported version. PHP 7.1 and 7.2 have new features that will improve the quality of the codebase. 7.2 will officially not be supported in a few months, but as a library, it is better to support the lowest version possible. And 7.3 doesn't offer compelling features to not support a still-officially-supported version. I think the next version jump will be to 7.4.

PHPUnit does not support versions 6.0 or 7.0 anymore. 8.0 is their minimum supported version. It is tied to PHP 7.2.

The root namespace qualifier, while minor, does improve performance. But more importantly, it communicates explicitly where the function is from and that improves readability. Further, we are already doing the root qualifier on constants, so it will be consistent with the coding style of the project.

Approach

I will create a 1.0 branch and a 2.0 branch. I'm still considering whether it makes sense to keep a develop branch around, or just do all development in the latest versioned branch.

My goal is to keep the scope of this small to get it done rather quickly, and have future development have access to the nice features of PHP 7.1 and 7.2.

Thoughts and comments welcome!

Beakerboy commented 4 years ago

I’d suggest organizing some of the “conceptual elements” as well. For example, I’d move the Polynomial class from Functions to Number. Also the interface on the Interpolation class seems awkward. I’d make it consistent with the Regression class (which is awkward in its own way). Maybe look at how other packages manage these features. At least one has a Method/Model approach that I used in the regression classes.

markrogoyski commented 4 years ago

Hi @Beakerboy, Thanks for the feedback.

I would like to release version 2.0 soon and with no breaking changes that requires someone to update their code. If they are on PHP 7.0 there is nothing I can do about that, but if they are already on PHP 7.2 or higher, I'd like version 2.0 to just work. I'm thinking to make bigger breaking changes for version 3.0. A lot of the giant associative arrays I'd like to make objects for and perhaps reorganize namespaces and interfaces as you suggest. Any other bigger, breaking changes you have in mind let's plan for that release. As a library, I'd like to be able to improve things and offer new functionality as often as possible without requiring someone who is using the code to have to fix things to get a new release to work most of the time. So, for version 2.0, no changes for the user. Then in version 3.0, make a whole bunch of big changes that will require a user to do some migration. At some point you have to break compatibility and require a migration, but I'd like to limit those releases. And when we do do them, do as much of the breaking changes as possible in a single release so the subsequent releases are simpler changes, like supporting newer PHP versions which don't require a migration for the end user.

For your suggestions, I think we can do the Polynomial move by simply copying the class and labelling the one in Functions as deprecated. Older code continues to work with the new version, and there is a period of time where it is known that the functionality will go away and require changes (in v3.0).

I agree that the Numerical Analysis/Interpolation stuff seems "different." Jakob owned that code and kind of dropped off in contributing. I don't have a grand master plan for it. I'm open to suggestions. Maybe a good thing to refactor and provide a consistent interface in version 3.0?

Beakerboy commented 4 years ago

My understanding of semver is, you can mark functions and classes as deprecated in ver 1.3.0 and say, “deprecated in 1.3 and scheduled for removal in 2.0.0.” Nobody HAS to change their code, but if they do, then they can immediately upgrade from 1.3.0 to 2.0.0. It would be one fewer branch to actively maintain.

sicilian-najdorf commented 4 years ago

@markrogoyski i am just wondering if you already tried to bench mark this with php 8. jit improves the speed of math operations.

markrogoyski commented 4 years ago

Hi @sicilian-najdorf, I have not tried it with PHP 8 yet. It will be interesting to see if PHP 8 brings the same kind of measurable performance gains that PHP 7 did.

Since everything is forward compatible, any user that upgrades to PHP 8 will see the performance benefit. The minimum version we support doesn't affect that.