Welcome Guest, Not a member yet? Register   Sign In
Do you need very strict Backwork Comapibility that prevents CI4 development?
#1

(This post was last modified: 01-01-2022, 07:07 PM by kenjis.)

I want to hear from you all.

Now the CI4 maintainer team has very strict Backward Compatibility policy.
We cannot change the method signature like the following:
PHP Code:
-public function map(array $routes = [], ?array $options null): RouteCollectionInterface
+public function map(array $routes = [], array $options = []): RouteCollectionInterface 

Even if it is changed, almost all users app does not break. But if a user have extended CI4 RouteCollection class and overrides the method,
the extended class would raise error. So we cannot change it in version 4.x. (We can change in 5.0, but there is no 5.0 yet).

In CI4, in fact there are a lot of non good signature like it, but the policy prevents to fix them.
It keeps hampering development because we can't fix the not-so-clean code for a long time.
It puts stress on developers/contributors.

I just want to hear from you. Do you really need such a very strict Backward Compatibility?
Reply
#2

In my opinion, if the developer does not extend the base classes, then such changes will not affect the performance of the application in any way.
On the other hand, if a developer extends the base classes by making changes or implements the framework's interfaces, then he (the developer) must in any case check the compatibility of his code with each release.

ps: Here array $routes = [] specifying a default value is pointless.
Reply
#3

As long as it's well documented what changed and what's the new syntax, I don't care for minor breaking changes.
CodeIgniter 4 tutorials (EN/FR) - https://includebeer.com
/*** NO support in private message - Use the forum! ***/
Reply
#4

Same here as @includebeer said likewise.
What did you Try? What did you Get? What did you Expect?

Joined CodeIgniter Community 2009.  ( Skype: insitfx )
Reply
#5

(This post was last modified: 01-02-2022, 11:55 PM by tgix.)

Yes, backward compatibility is a must. I want to be able to move from 4.1.4 to 4.1.5 without any hassle!
I am 100% in favor of fixing these broken signatures. BUT - please schedule a separate release ONLY for this - don't roll this into a release with myriad of other things that may or may not break. Land a final 4.1.x release and then make a 4.2.0 (or 5.0.0 if that's what the CI Charter stipulates) with all these signature changes and only these changes! 
You will then have a 4.1.x branch for important bug fixes (supported, say 3 months) and us users may test and migrate to 4.2.0 (or 5.0.0)
Reply
#6

(This post was last modified: 01-09-2022, 01:19 AM by kenjis.)

Thanks all.

My example that changes method parameter from nullable to not nullable was bad.

?array $options = null → array $options = []

Because in fact, it does not break extended classes.
https://3v4l.org/OYbIf

In this case, if a user calls the method with null like map([...], null), it causes a fatal error.
But it seems nobody does like that.

At least, no one here objected to minor method signature changes in minor version up, e.g., 4.2.0.
The assumption is that we describe breaking changes clearly in the upgrade notes.
Reply
#7

Here’s my take. Semver is crucial in our modern “dependency management” era to imbue meaning into versions. It is the only thing that gives common ground across all the different pieces that go together to make up an “app”.
The most important piece of Semver is the breaking changes: using `^4.0` notation in Composer *must guarantee* that an update won’t break your app.

Now the caveats… Though it isn’t stated in the docs, I believe Semver is based on the principles of strong dissociation between the code’s internal work and it’s public API. Since Semver *only applies to the public API* there is significant work that will always be done to the internal code without affecting versioning. Here’s our first big problem: CI4 has very weak boundaries between internal code and public API. Another way of saying this: way too many classes, methods, and properties are “public” or “protected” when they should be “private” or “final” or “internal”.
What does this mean? This means that changing the signature of an insignificant protected method counts as a change to the public API and thus is a “breaking change”. Does this mean we *absolutely cannot* make these changes? No, but every one must be accompanied by a “BREAKING CHANGE” warning in bold User Guide and, to the casual reader, makes CI4 look bad.

So how do we fix this? The most important fix is to go to the root and establish strong internal/public boundaries - but this would be such a large and sweeping backwards-incompatible change that it would require a major version (hint: this is coming in version 5). So we are left with small and deliberate changes, identifying methods and areas of the code that are not as they should be and making those breaking changes with caution and documentation. We still avoid deliberate changes which would under all normal circumstances result in a major version.

One last thought… Semver has a bit of an unusual definition for “bug fix”:
> A bug fix is defined as an internal change that fixes incorrect behavior.
I got to CI4 after most of the initial code was written. I stand on the backs of developers who volunteered lots of hard work and many hours to write that code - most of whom are not around anymore. In my opinion, there is a fair amount of “incorrect behavior” in the way things were originally written (not faulting anyone, we all have our weaknesses). So I ponder this question myself and invite you to as well:
Can we modify intentional behavior that we disagree with and release it as a bug fix?
Reply
#8

I got a brilliant idea. End support for 4.x and release only patches with fixes.
Start work on 5.x =)
Reply
#9

(This post was last modified: 01-09-2022, 06:06 PM by kenjis.)

I would like to loosen the current Backward Compatibility policy.
Because the disadvantages of the policy seem to outweigh the benefits.
- if we keep the strict rule and we wait for v5, it takes too much time (v5 does not seem to come in a year or so).
- the current strict rule is preventing contributors/maintainers contributions (many developers wants to work with cleaner code).
- if we keep the strict rule, we might lose contributions.
- in the first place, CI4 does not have a stable enough APIs to guarantee Backward Compatibility. (Following SemVer is impossible, or we must count up major version every time when the release includes breaking changes.)
- nobody seems to want the strict Backward Compatibility policy. It seems many users accept minor changes with clear documentations.

If we loosen the rule, we can fix many *incorrect* method signatures, and can add missing type hints. (CI4's type coverage is very low.)

The new rule is:
- We can change method signature with minor version up, unless these changes do not break the normal users existing apps.
- What is the normal users existing apps:
  - apps which uses public methods (not having @internal) of CI4
  - do not extends CI4 classes
  - do not purposely specify the default value like null in the method calls

And if we accept the new rule the following PR is acceptable in v4.2.0:
https://github.com/codeigniter4/CodeIgniter4/pull/5509

(01-09-2022, 06:00 AM)MGatner Wrote: One last thought… Semver has a bit of an unusual definition for “bug fix”:
>  A bug fix is defined as an internal change that fixes incorrect behavior.
I got to CI4 after most of the initial code was written. I stand on the backs of developers who volunteered lots of hard work and many hours to write that code - most of whom are not around anymore. In my opinion, there is a fair amount of “incorrect behavior” in the way things were originally written (not faulting anyone, we all have our weaknesses). So I ponder this question myself and invite you to as well:
Can we modify intentional behavior that we disagree with and release it as a bug fix?

A bug fix can be included in a patch release.
I think it is safer that method signature changes are not included in a patch release.

> Software using Semantic Versioning MUST declare a public API. This API could be declared in the code itself or exist strictly in documentation. However it is done, it SHOULD be precise and comprehensive.
https://semver.org/#spec-item-1

If we follow SemVer, the first thing is to declare a public API.
How about like this?

The public API is all public methods and functions in the framework that are documented in the User Guide and not having @internal in the doc comments.
And we consider all the methods as *final*, even if it is not declared with the final keyword.
And we do not guarantee the default values of the parameters are not changed.
Reply




Theme © iAndrew 2016 - Forum software by © MyBB