Added initial version of our BC promise

[Toflar]

This is quite an important one so I've requested a few people for review.
Please feel free to notify other Contao devs if you think they would like to extend/modify this document.

[m-vo]

Let's talk constructor parameters again.

Personally I think the exact dependencies I'm injecting into a class (that do not leak out via class methods) should be considered implementation detail: If I want to change an algorithm for instance, I'd like to be able to exchange LibraryAGenerator with LibraryBProvider, if I want to improve 'testability', I'd like to insert new dependencies - e.g. a FilesystemAbstraction.

So, when does this hurt anyone? Basically whenever there are calls to my class's constructor with a now changed (and incompatible = no respective optional parameters) signature due to...

1. ... someone creating an instance of my class.
2. ... someone calling parent::__construct().

In a DI architecture where classes (services) are instantiated by the container 1) can be neglected. 2) is only the case when inheriting and there are only a few reasons someone should ever do this:

1. extending an abstract base class (Contao\CoreBundle\Controller\ContentElement\AbstractContentElementController)
2. extending a non-abstract class that is meant to be a building block (Symfony\Component\Console\Command\Command)
3. creating a fixture for testing (Contao\CoreBundle\Fixtures\Exception\DerivedPageNotFoundException)
4. overwriting features of a class (e.g. decorating a service & modifying bits)

Points 1) - 3) are legitimate use cases. 4), however, clearly is a misuse to me (the class is maybe simply not final due to point 4).

So how to work around this? Let's make an example: If I want decorate Doctrine's default AnnotationReader instead of extending and overwriting it I could also implement the Reader interface myself. And If I need to reuse code can inject the existing AnnotationReader and simply delegate calls. This composition pattern works whenever there are appropriate interfaces around.

Long story short, because all of you know where this is going anyway: 😄 I would vote for excluding constructors from BC promise and make some well-thought exceptions to this rule, namely to cover the above building blocks. Note that this is only true for the 'new' code, not the legacy classes inside Resources/contao.

(And imho those exceptions should be visible in code - e.g. with appropriate annotations. )

[xchs]

👍

[leofeyer]

I like the initial version and especially the following sentence:

everything that is about integrating Contao into a Symfony application might be subject to change

What we could discuss:

1. Constructor arguments (see @m-vo's arguments above)
2. Composer/ScriptHandler (integrating Contao into a Symfony application)
3. ContaoManager/Plugin (integrating Contao into the Managed Edition)

[Toflar]

Constructor arguments (see @m-vo's arguments above)

I don't think I will ever agree here.

Composer/ScriptHandler (integrating Contao into a Symfony application)

I don't think we need to mention this here. We won't be able to change that in any minor version so that must be covered by BC.

ContaoManager/Plugin (integrating Contao into the Managed Edition)

Added.

[m-vo]

don't think I will ever agree here.

Do you mind sharing why?

[Toflar]

Symfony protects all public methods that obviously includes constructors. Which makes sense because anybody can register their own services and use the classes the way they want.
And that's also the way it should be.
We cannot just adjust the constructor of e.g. a PictureGenerator. I might use my own instance of it with a different instance of ResizerInterface.

[ausi]

I’m not sure about the constructor arguments. For services it might make sense to exclude them from the BC promise. Should we set this to “up for discussion”?

[leofeyer]

There is no "up for discussion" label in this repo, but we should definitely discuss this. I have set up a reminder for the next call.

[aschempp]

I generally like the statement(s). Some thoughts:

• we might mentions that the template markup can change, but the template variables should not (the should only be extended).
• There is at least one compiler pass that is explicitly designed to be re-used by extension developers: https://github.com/contao/contao/blob/master/core-bundle/src/DependencyInjection/Compiler/RegisterFragmentsPass.php#L29

[leofeyer]

As discussed in Mumble on November 28th, we want to add a paragraph about constructors marked as @internal before we merge.

[aschempp]

Can we somehow link to https://symfony.com/doc/current/service_container/service_decoration.html here?

[aschempp]

I'm not sure this whole chapter is necessary if we simply mark them as @internal? All of the mentioned class types (except the Plugin) are also services, so they are already covered by you should decorate a service?