Make it easier to follow API changes in Rector

[tmotyl]

Feature Request

Thanks a lot for creating rector and making it opensource! I highly appreciate the what you do and I think this tool has a potential to change how the PHP ecosystem works.

I would love to see the community growing around Rector and more and more rules being created, specifically to help upgrading certain framework and applications (like https://github.com/sabbelasichon/typo3-rector).

However I see one major pain point, which makes writing and maintaining custom rules quite cumbersome and frustrating for me. Rector is evolving pretty quickly, and right it's hard to follow breaking changes in Rector API for everybody who develop custom rector rules rules in separate tools/repositories.

1. there is no way to see whether certain release will contain breaking changes. Semver is not followed as Rector patch releases often contain breaking API changes like class being renamed.
2. Even when you investigate the Rector commit history, you can't tell from the commit message that it contain breaking change. example: 28a55c9
   The commit message sounds "safe" while the commit contains tons of breaking changes.
   I've learnt it the hard way, by writing new rector using documentation on github (which was rendered already from master branch), and tried to run the code in 0.8.6 which did not work.

Possible solutions (and/or)

A) Rector provides rectors for breaking changes ;)
B) Rector publishes a changelog with breaking changes and for every breaking change information how to migrate
C) Commits with breaking changes have some indicator, e.g. [!!!] at the beginning of the commit message title
D) on top of that Rector releases first 1.0 version and follows semver
E) deprecate old code but keep backward compatibility for at last one major version

Maybe you already have a plan to address this issue somehow?

Please don't get me wrong. I really appreciate the awesome support Thomas and other rector contributors are providing. Many times we've got direct help when trying to upgrade our library to newer Rector version. But the more external rector rules there are in the wild the more important it will be to have some upgrade helpers.

[TomasVotruba]

Hi Tym,

thanks for thinking this through and thank you for opening this issues in such a nice way.

Rector will go through more changes in the future, it's self-refactoring tool after all. In last 2 months we added completely new set called naming, that basically affect every PHP element that has a name that can be inferred. A class by type, a method by return type, a constant by value. I think we can expect more changes to come in the future.

Most of these BC breaks can't be covered by Rector, or it would be very complicated one-time-use rule, that might skip some edge cases.

I'm not sure keeping changelog or writing the "how to" will help. It will only describe lot of work in more explicit way.

Symfony is doing great job at describing these BC breaks, yet in the scale it's lot of extra work, that only slowls down developers. Thus Rector was made to remove this problem. And it works. If you upgrade Symfony 2.x to 5.x, with Rector there is minimum reading of Symfony CHANGELOGs, unless something edgy happens.

That's somethign I'd like to follow here to, as I'm very lazy, Rector users are super lazy and from this issue I feel I'm not the only one :). If we make a BC break, all the rules in Rector core are upgraded at once. It kind of does not make sense to develop Rector rules in slower paste, as they directly depend on Rector.

---

What Could Work?

Saying that, in the past had an idea of centralized rulesets. A ruleset for each package, that are direct part of Rector. First version of this idea you can see at /rules directory.

Using single repository for rules brings these benefits:

• if a Rector changes, all the rules for Symfony change too, at once, so there is no BC break - 0 upgrade work
• if something breaks during this upgrade, we know about it the instant it happens and fix it before pull-request gets merged
• if Symfony (or any other project) requires a new rule, it can become generic and useful to other
  projects - that happens quite often; I've actually noticed few duplicated rules, that are already implemented, why not join the forces?
• closer connection to maintainers, we can implements their features requests much faster, then if proposed in some external repository
• better quality of custom PHPStan rules that help use write better Rector rules more easily

Not a fantasy, but a reality:

• this already works great with @cakephp community - we added couple of 3.x rules ourself, but the rest was added by the community - how much troubles they had with upgrading all their custom rules? none

Saying that, I'd cosinder moving rules to /rules/typo3 or similar, because that would remove all the maintenance hell from both your side as rule maintainers, and our side as core tool developers.
Also, all other open-source projects would benefits from your custom rules, that might be promoted to generic rules.

What do you think?

[staabm]

Regarding the inital question: would it make sense to add some automation which helps dectecting breaking changes, or at least makes them visible so they could be put into the changelog in some form?

i have https://github.com/Roave/BackwardCompatibilityCheck In mind

[maddy2101]

Hi, let me chime in as a mere user: I just got a symfony project that I need to update. The current version used is symfony 3.2.
Can you imagine how long it took for me to find a version of rector that is compatible?
In short: I did not manage at all, but updated the project blind to symfony 3.4 latest, and then hand picked rector version ^0.5.

This is the other part of Tymeks request: integrating rules for frameworks is nice, I applaud to that, even if it might cause the rector to explode with rules from all over the place, that will be dealt with in due time.
But for a user, who just wants to install rector as a dev dependency in order to maintain their project, it would really be helpful to have a reliable versioning.
You can really be generous with the major versions, it will not hurt to bump them each time a new dependency (esp. symfony) enters the stage, simply because it eases maintenance on client projects.

Please consider jumping to semver, and keep the dependencies and API stable within the major versions.
I promise I will not complain if you give me a new major version every other month.

[tmotyl]

@maddy2101 In case of your symfony project I would not install rector in the project composer, but use rector in docker or use prefixed version of rector (so it doesn't conflict with project requirements) - see https://github.com/rectorphp/rector#install

[maddy2101]

well, that is a possibility, too. Thanks for the pointer.

[TomasVotruba]

@maddy2101 Hi Maddy, I wish you asked me earlier to save the trouble.

There is prefixed Rector for that as @tmotyl said. Here: https://github.com/rectorphp/rector-prefixed

I actually use the latest Rector Prefixed on upgrade of Symfony 2.8 app running on PHP 7.1, even without Docker.

[maddy2101]

don't bother, that happens when one does not read the ReadMe. My fault entirely. :)

[TomasVotruba]

Any follow up to this or shall we close it?

[TomasVotruba]

Converted to Discussion, that were introduced today on GitHub Universe.
Let's try it out :) Looks like stackoverflow so far

[leoloso]

I agree that you may want to consider following proper SEMVER for tagging the releases moving forward. I know that Rector is going so fast that soon you'll be in version 17 😂, but at least nobody will get a broken version. You could then encourage developers to use >= instead of ~ for requiring Rector in composer.json, so they keep getting the latest features, but they can also stick to a certain version that they know works will with their set-up.

In my case, I'm using Option::EXCLUDE_PATHS in my project, and I've seen you've changed that to Option::SKIP. If you tag the upcoming changes as 0.8.57 then my project will break. But if you tag it a 1.0.0 then I can handle it better

[TomasVotruba]

We're following semver actually :) The 0.x follows different rules.

.

The discussion is rather about how to keep all rules up to date, whereever they are.

We can see composer-dependency approach fails, Symfony, Doctrine, Laravel ecosystem are lagging behind new version many months, sometimes years.

The best way I see now is: #4222 (comment)

[leoloso]

Ok

Notice that in Composer for pre 1.0 version, if there are breaking changes, it's expected you'll change MINOR and not PATCH:

For pre-1.0 versions it also acts with safety in mind and treats ^0.3 as >=0.3.0 <0.4.0.

[TomasVotruba]

That's useless, as anything can change anytime.

[TomasVotruba]

Good News 🥳

I've got some good news on this topic 🙂 In Rector 0.10 we split community packages from core repository:

• https://packagist.org/packages/rector/rector-symfony
• https://packagist.org/packages/rector/rector-laravel
• https://packagist.org/packages/rector/rector-doctrine
• https://packagist.org/packages/rector/rector-phpunit
• https://packagist.org/packages/rector/rector-nette
• https://packagist.org/packages/rector/rector-cakephp

Now we experience similar problems like your package that use Rector first hand.

1. Saying that, we've added UPGRADE.md file to include most notable changes:
   https://github.com/rectorphp/rector/blob/main/UPGRADE.md

2. It was about time to eat our own 🐶 food :) so since Rector 0.9 we're adding upgrade configs to upgrade Rector
   https://github.com/rectorphp/rector/tree/main/upgrade

E.g. to upgrade to Rector 0.10, just run:

vendor/bin/rector process src --config vendor/rector/rector/upgrade/rector_010.php