Deprecating changes for 1 release instead of removing

[barryvdh]

What do you feel about 'officially' deprecating methods that are to be removed? (Where reasonably possible).

For example:

share Method Removed - The share method has been removed from the container. This was a legacy method that has not been documented in several years.

Instead of removing them directly, can't we deprecate them first, for a single release?
Similar to Symfony; http://symfony.com/doc/current/contributing/code/conventions.html#deprecations

A feature is marked as deprecated by adding a @deprecated phpdoc to relevant classes, methods, properties, ...:

/**
 * @deprecated since version 2.8, to be removed in 3.0. Use XXX instead.
 */

A PHP E_USER_DEPRECATED error must also be triggered to help people with the migration starting one or two minor versions before the version where the feature will be removed (depending on the criticality of the removal):

@trigger_error('XXX() is deprecated since version 2.8 and will be removed in 3.0. Use XXX instead.', E_USER_DEPRECATED);

So trigger a silent deprecation error, and add a custom error listener to show them only in dev mode, log them, show them in de debugbar etc.

This would ease the transition between upgrades for application AND packages.

(And if a half year is too long, perhaps start deprecating them half-cycle as they occur, so you will at least receive them earlier)

[franzliedke]

Sounds like a very good idea for a project the size of Laravel, especially considering its versioning scheme. 👍

[Garbee]

(And if a half year is too long, perhaps start deprecating them half-cycle as they occur, so you will at least receive them earlier)

I'd love this. If we know something is deprecated with the next version, why not go ahead and mark it as such in the currently supported versions as well? This way even those minor updates to existing systems starts to provide developers feedback about what to expect in the future.

[RemiCollin]

Big +1 on this. Especially for package maintainer, this would drastically reduces the time taken to catch up on every new release.

[mpociot]

Yes - please!

[viezel]

+1

[CristianLlanos]

👍🏻

[fergthh]

+1

[Garbee]

It only adds a barrier in a few cases. Typically, anything "removed" is renamed or tweaked to be completed in a different way. So the methods can stick around, be deprecated but proxy the future code. Giving developers time to update their code without having to do a swift run-through and deep QA check to avoid oddball breakage.

For the few places where it would be a problem, we can handle those as they occur in a meaningful way to let developers know problems will occur in future updates.

[franzliedke]

@garygreen I don't use Laravel because of its "fast moving pace". I like its philosophy, its expressive code and its rich feature set. In fact, breaking changes annoy me.

IMO, frameworks like Symfony and, for example, Ember.JS, that have a well-thought-out deprecation process, show that it is possible to stay innovative and keep moving ahead without frequent breaking changes - even in the JS ecosystem, which likes to move at breakneck speed.

A changed process would lead to different behavior, and likely would result in new features etc. being more carefully considered in terms of their longevity. From my perspective, that's a good thing.

[jbrooksuk]

@garygreen I don't use Laravel because of its "fast moving pace". I like its philosophy, its expressive code and its rich feature set. In fact, breaking changes annoy me.

Did you know that you can lock your dependencies down to an explicit version? This shouldn't affect your position on Laravel, because it's up to you to manage your dependencies :)

[franzliedke]

Of course I do. How does that help me when I want to use new features but can't because old ones are changed?

[jbrooksuk]

That's up to you to manage as part of your upgrade paths.

[franzliedke]

Well, I appreciate @barryvdh's suggestion. Laravel has obviously been leaning in the "meh, just go with it" direction for the last few years. I think it would be wise for such a widely-used project to acknowledge this wide usage (along with all its diversity), which includes developers that grow tired of so many updates, and don't always have the time / resources to do so - or have better things to do.

That's all. :)

[Toyinster]

Sensible suggestion - was thinking exact same thing on the Laravel 5.4 upgrade

[barryvdh]

Laravel does not follow SemVer, but I know it tries to avoid BC breaks in mino versions when possible.
I don't want to slow down development, just whenever something becomes deprecated, clearly document it. And when possible, allow a transition period.

[LKaemmerling]

Ahm no that is clearly wrong. Not all Breaking Changes are documented in the Upgrade Notes. Such Things like the rename of TestReponse->seeJson() to assertJson() or something else aren't documentated.

[barryvdh]

Just a few examples where you could have a deprecation message before removing:

• Container share, could have been deprecated and then removed in favor of singleton
• Session set, (could point to put)

And where aliases could be used:

• Router middleware -> aliasMiddleware
• Router getParameter() -> parameter
• Collection every -> nth()
  etc

And I agree that this doesn't make much sense for apps, but for packages it can be a bit annoying, on every new version it just breaks a bit. Would be a lot more relaxing if more just keeps working but people can report/fix deprecated errors in 6 months instead of rushing out version_compare or method_exists hacks..

[barryvdh]

Yeah well multiple issues were added only after it broke and we noticed it wasn't yet documented..

[garygreen]

after it broke and we noticed it wasn't yet documented..

Well if that's the case then that's bad. The upgrade guide is the single source of truth for what is breaking, so it should definitely be documented.

On reflection we did actually have similar problems when lists was removed from collection and query builder, that is another example that could have been deprecated beforehand and would have saved a bit of headache. I think if it's not going to cause headaches to deprecate something for one release, then 👍

[Jeroen-G]

How is "allow a transition period" not going to slow development down? By allowing a transition period, i.e. one release, you are slowing development down.

No, you are not. The moment a new Laravel version is released, everyone wants to go develop with its new shiny things. If package X depends on a function that is removed it would take more time before that package can be used on the new Laravel version. If the function gets deprecated, the X's maintainer can issue a compatible release the same day and have more time to work on a replacement of the deprecated function without slowing down the development of its users.

[garygreen]

I think we're talking about different things here. I completely agree that deprecating smaller changes is worthwhile, I'm talking about a bigger feature that requires something to be breaking and won't work in the next version without it. Then you are delaying shiny feature X because of this deprecation rule. I'm all for this change if it doesn't delay development, that is all.

[Garbee]

The rule should only apply to things that can be aliased. The recommendation is for methods that get modified. Typically, there is a way to allow the previous name/signature while still having the new stuff as well. Which means the deprecations are generally always applicable to be kept around for one release once the decision is made. We aren't talking about things like the bus system rework where it went from dual-class to self-handling.

Although, any interface/class renames would also be nice to leave a deprecated alias item in place for a version. As was done before for the SelfHandling interface iirc.

[RyanThompson]

No brainer - have to properly deprecate if you want to move forward and not burn bridges. Take note from Symfony.

[taylorotwell]

We will attempt to deprecate removals for 1 release in the future.

[jbrooksuk]

Nice!

[barryvdh]

So like this: laravel/framework#20024
That breaks al lot of packages, without warning.