Update plugin documentation

[sagikazarmark]

No description provided.

[dbu]

i added WCM to the title (waiting for code merge).
we need to merge php-http/client-common#14 first.

content wise i agree, looks good. can you check travis-ci?

[dbu]

this will only be correct once we have released 1.1 right? we might want to add a versionadded block in strategically relevant places to explain what was changed in 1.1

[sagikazarmark]

What is versionadded?

[dbu]

http://symfony.com/doc/current/contributing/documentation/format.html#new-features-or-behavior-changes

[sagikazarmark]

And what would be the format? Since from the documentation point of view we haven't added anything, but changed. Would it be "Since client-common 1.1 Plugins are part of that package" or "Prior to client-common 1.1 it was a separate package"?

[dbu]

look at the second example in the symfony doc i linked. here it could be: ``` .. versionadded: 1.1 The namespace was adjusted in version 1.1 and the old namespace deprecated but will still work until version 2.0. When working with version 1.0 you need to use `Http\Client\Plugin\Plugin` instead. ```

[sagikazarmark]

👍 I will add it.

One more though: we probably have to always mention the package as well, since the versioning is not aligned between repos.

[dbu]

right, good point. so lets be even more explicit and say something like

The plugins where moved to the clients-common package in version 1.1. If
you work with version 1.0, you need to require the separate plugin
package. The new interface will keep implementing
Http\Client\Plugin\Plugin until version 2 but relying on the old
interface is deprecated.

[sagikazarmark]

The new interface will keep implementing

Hm, this is not true, and even if it was, it should be the other way around IMO: the old interface should extend the new one.

[dbu]

The new interface will keep implementing

Hm, this is not true, and even if it was, it should be the other way
around IMO: the old interface should extend the new one.

but then we have a BC problem i think. if i wrote code with the old interface, it should keep working until we go to 2.0. so the new interface should extend the old interface. or did we say for this edge case we do a BC break?

[sagikazarmark]

Technically, there is no BC break. The "old" plugin client is still available in the old plugin package. If you want to use the old plugins, you still can with the old client.

What I could imagine is to extend the old plugin interface with the new one, so that old plugins work in the new client as well, but I don't think we have to maintain it vica versa (new plugins in the old client).

There is already kind of a PR for that: php-http/plugins#64

[dbu]

okay, you are right i think. if i don't want to upgrade, i simply keep using the 1.0 plugins and plugin client.

[sagikazarmark]

Yup. We might even support both in HttplugBundle?

[dbu]

i'd rather not add that overhead in the bundle.

can you add the versionadded blocks and then we merge this?

[sagikazarmark]

Yep, working on it, also adding deprecation notice to plugins. It seems after all, that we might be able to have cross-compatibility between the new and the old client, plugins. PR coming.

[sagikazarmark]

Done. Can you check @dbu?

[dbu]

If you work with version 1.0, the interface is called Http\Client\Plugin\Plugin and you need to require the separate...

[sagikazarmark]

Done

[dbu]

👍