Add a 'deprecated' module that includes deprecated functions only when enabled

Deprecated module then loads $module.deprecated.php for any module you have install that has that file, so the functions become available.

I think we can do even better and just load the *.deprecated.inc file of all modules that the given module depends on.

Mh, this would require you to either recursive go through the dependency graph or potentially specify each submodule. For example someone would use some methods of comment, and comment still uses node related methods internally.

I was thinking of putting stuff in field.deprecated.inc as well.

Having a deprecated.module that loads all *.deprecated.inc in all enabled modules sounds good enough functionally. Being smarter seems like it could add unneeded complexity.

That's still like 50 if (file_exists()) on each request though. Other possibilities:
- add deprecated_load($module) in common.inc (or in \Drupal ?) that does if module_exists('deprecated') {require $module.deprecated.inc)}, and let each module call it at the top of its .module file
- be even simpler and let each module do the test in its own module file.

At this point, there's no code in deprecated.module, and maybe we could use a simple setting for the killswitch instead of an empty module ?

Also, is this about functions we intend to remove before 8.0, or functions that are here to stay ?

Hm. While I like the simplicity of dependencies: deprecated as a solution, I'm not sure for Drupal 8.

My reading of http://buytaert.net/drupal-8-api-freeze is that we want to vastly minimize API changes that would affect module developers, so they can start to port their stuff with some degree of confidence. And if module developers are suddenly getting fatal errors about undefined functions until they do something (either add the info line or include the deprecated.inc file manually), what's the point in doing @deprecated at all? And this "all of a sudden fatal errors" thing would happen to developers randomly throughout the rest of the release cycle as we commit more and more patches that convert away from procedural wrappers which then get moved around. The end result is APIs would never be truly frozen, because you'd never know from git pull to git pull when something was going to bite you. :\

Also, FWIW, I actually love that we're keeping the one-liner wrappers around for a release. I see it as a bit of an olive branch to module developers who now have to grapple really tough new concepts like namespaces and "use" statements, convoluted directory structures, plugins, controllers, services, dependency injection, etc. etc. in order to write even basic modules. At least something can look familiar for awhile. ;)

My goal for a *.deprecated.inc file is mostly to move old, crusty code that is only here because we got too late to the point where we could actually remove it, out of the way of the "real D8 code" of the module.
You can look at a module, discarding its .deprecated file, and get a clear grasp of how you're "supposed" to use it in D8, uncluttered with stuff that's only here for legacy / BC.
It also really helps as a maintainer of said module. Keep BC clearly separated from your .module file.

For all I care, I could go with a pure convention approach, where each impacted module manually and unconditionally included its own [module].deprecated.inc file at the top of its own .module (like field.module currently does for field.form.inc, field.crud.inc...).

I thought we had an agreement on removing all the @deprecated before Drupal 8.0 ships?

Obviously it doesn't make sense to deprecate something if we don't have a valid replacement, or haven't even started thinking about a replacement (as we started doing, for example, in #788900: Deprecate and remove usages of arg()).

Side note: #2067127: Reorganize the contents of field.* files does the move for field.module @deprecated functions, and introduces field.deprecated.inc - unconditionally loaded for now (as in current HEAD), but doing this sooner rather than later helps us have a clearer vision of the stuff in field.module

What about deprecated early bootstrap level functions (which also exist AFAIR)? While some deprecated functions may be moved to the module level, some are not.

An alternative solution to the same problem is being discussed in #2158871: [Policy, no patch] Clearly denote when @deprecated code is slated to be removed

Is not it a time to move deprecated code to sandbox deprecated module? see related ajax issue in #2187735-3: Add removal information to docblock of all @deprecated functions

Back in the day, Drupal 4.6 had a "legacy" module for old versions of functions and such. I would not be adverse to such a module being revived, provided it was not enabled by default (meaning core doesn't use it). :-)

+1 to this idea. It would make D8 that little bit leaner if you didn't need/want the procedural stuff. @webchick's concerns in #6 are pretty valid, but are solved by simply setting deprecated as a dependency of the module you're porting to D8 until you're sure that you've removed all the procedural bits from what your module is doing (as per the issue summary).

Is it too late to get this in?

FWIW, there is a high profile example of a framework successfully doing this recently in the jQuery Migrate plugin between versions 1.8 and 1.9, where multiple previously deprecated functions (that I'm sure were still in high rotation) were removed such as browser(), live() and die().

@catch - If you have a look at #2093143: [meta] Remove calls to @deprecated and "backwards compatibility" procedural functions from core, I'd suggest flagging a function to be moved to the deprecated module (or in a deprecated .inc file) the moment Core no longer calls it internally. This way, there's no chance a future patch commit will accidentally re-introduce functions that we're trying to clean up (we had this problem a lot when trying to remove theme() and ended up renaming the function), and you can draw a nice, easy line in the sand over there and even schedule a date ahead of time.

only starting from 8.1 we can ship the module

Hm I don't think so. If we do this, it would probably be ideal for it to be in 8.0.x so modules that don't plan to chase HEAD could depend on it right out of the gate.

@webchick I suppose there's no functions in 8.x that are deprecated in 8.1 and later everything was moved to 9.x for removal, so maybe we need another issue about moving some deprecated in 8.x to the module and change policy

Right, this issue is about "Add the module" and not "Move things into it."

it could be used for jQuery 3.0 "migrate" library to keep compatibility with 2.0 - related #2533498: Update jQuery to version 3

As we have https://www.drupal.org/core/deprecation deprecation policy, is this issue is outdated?

I think so, yeah. This can probably be closed.