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. :)