Howto handle hook changes

I have a hook which needs to be changed. In essence it needs an additional argument.

The problem is, that plugins should be able to use the new argument, but still work on older versions where the argument didn't exist yet.

If I add the argument and use it in the hook implementation in the plugin, then the plugin doesn't work with older versions anymore: Argument(s) ... are declared in the hookimpl but can not be found in the hookspec

Using kwargs with defaults also doesn't work, the argument isn't passed then.

If I add a new hook, then both my implementations in the plugin are called, because the old hook still needs to be called for older plugins.

One idea would be the possibility to mark a hook specification deprecated with the name of the replacement and then when loading a plugin and it implements both hooks forget about the old hook. If it only supports the old hook, then add a warning about the deprecation.

Start by reviewing the hook specification and plugin-loading behavior described in the issue, then inspect how hook arguments are validated and how plugins implementing old and new hooks are handled. Define the compatibility behavior for old and new plugins, including deprecation warnings and avoiding duplicate calls, and add tests covering those cases.