Bernhard of Symfony has posted a PR for Symfony's Backward Compatibility (BC) policy/promise here: https://github.com/symfony/symfony-docs/pull/3439

He specifically reached out to us for Drupal's input, as we're a major user of Symfony's components. I've left a few small notes, but I'm also leaving this here to get feedback from others. There's 2 questions:

1) Are we, as a customer/consumer of Symfony, OK with this policy? This can be discussed here, or specific constructive comments left on the PR above. (Don't flood them, please.) I can also aggregate comments upstream if we'd rather have a single channel/voice (which may be wise).

2) Can we use this model for our own BC policy? I think it's a good way to structure it, and communicates intent while allowing us a little wiggle room going forward with the new release plan. We've discussed using @api, and we're already using @deprecated. Adopting the same or a very similar policy for Drupal 8 could help clarify the "we won't break APIs, but not everything is an API" fuzzy statement we've made for 8.x releases.

To not block Symfony, I'm going to ask that we time-box the first question to the 31st at the latest. We can continue to talk about our own approach after that, but any feedback we have for Symfony should be presented and addressed before then.

Comments

Crell’s picture

Issue summary: View changes
msonnabaum’s picture

You cannot safely implement the interface. The interface may change, but all changes will be documented in the UPGRADE file.

To me, this means we could never upgrade symfony in a point release. Upgrading core cannot cause a fatal error in my contrib module because I implemented an interface. Either that, or we consider all of symfony's interfaces private and provide our own instead.

webmozart’s picture

To me, this means we could never upgrade symfony in a point release.

A stated in the document, you can implement an interface that is tagged with @api (and we won't ever remove @api once we put it there). If you implement some interface that is not tagged as @api, just request it on the issue tracker and we'll consider whether it's safe to add the tag or not.

The simplified distinction between @api/non-@api is: If a class/interface/method is tagged @api, you can extend/implement/override it safely and we guarantee to not break your code. If it is not tagged, you can still use it safely (construct, call), but overrides/implementations may need to be adapted to further releases (for example if we add optional parameters to a function signature, or if we add new methods to an interface).

rcross’s picture

perhaps its just semantics, but I think the way that is worded is off-putting.

A possible improvement:

Implementing this interface is not guaranteed stable across point releases. The interface may change, but all changes will be documented in the UPGRADE file.

catch’s picture

The simplified distinction between @api/non-@api is: If a class/interface/method is tagged @api, you can extend/implement/override it safely and we guarantee to not break your code. If it is not tagged, you can still use it safely (construct, call), but overrides/implementations may need to be adapted to further releases (for example if we add optional parameters to a function signature, or if we add new methods to an interface).

This seems reasonable to me, and I can see us having to do it for Drupal's own code in minor releases as well. It does mean we'd need to go through and audit all the Symfony interfaces/classes we're using to see what's tagged vs. not.

cdnsteve’s picture

My 2 cents.

Drupal needs a BC policy:
Having a Backwards Compatibility (BC) Policy makes people feel safe. As you likely already know, the corporate world likes these kind of assurances. Developers also like these kind of assurances. Making an investment in software is like picking a marriage partner.

Enterprise users are generally slower to accepting change. Having a clear roadmap and policy that enforces this is a major benefit. As developers start to build and extend things far beyond a CMS with Drupal 8, I sure want to know what BC contracts are in place.

Otherwise, some may feel they would be more comfortable using other software that does enforce this for larger builds. In some cases that would make sense to use something else, in others it would be regretful if Drupal was left off the table for this reason.

Garrett Albright’s picture

Thank you, cdnsteve, for elaborating on what the "BC" stood for and removing a major point of confusion on this issue.

Agreed that "guarantee" is a better word than "safe" here. The latter implies security, and a thought early on when going through these threads (other than "what the heck does BC mean?") was "so this is about labeling methods and objects with insecure code in Symfony?"

Crell’s picture

Title: [Policy, no patch] Symfony BC policy statement » [Policy, no patch] Symfony Backward Compatibility policy statement
Issue summary: View changes
webmozart’s picture

Thanks everyone for the feedback. I tried to improve the wording, the change set can be seen here:
https://github.com/bschussek/symfony-docs/commit/6d9edf14705864424ec5c40...

And a link to the full document:
https://github.com/symfony/symfony-docs/pull/3439/files

As always, feedback and improvement suggestions are welcome.

webmozart’s picture

I simplified the description some more. Hopefully this will remove some of the confusion:
https://github.com/bschussek/symfony-docs/commit/8c6c7bf5b31a4cadde04fbf...

cdnsteve’s picture

I like the guarantee phrasing, nice improvement.

It kind of goes with the Drupal motto - don't hack core. Or, don't hack @api, extend or implement it!

I would like to see Drupal 8 make interface and class references to critical points of the application using the exact same syntax: @api to keep consistent. That way developers don't have to remember @api for symfony, @drupalcontract or whatever syntax for something else.

cordoval’s picture

@crell are you managing a list of api interfaces that Drupal uses somewhere, i am very interested in helping auditing these.

For all others i think drupal has to split this issue into having a policy themselves and have a clause there how to deal with the symfony promise.

Crell’s picture

I'll go a step further: Symfony's plan seems reasonable, and the only question is if we should ask them to mark anything else @api. We should then adopt the same model ourselves, for which the only question then is which classes/interfaces we tag @api or @internal.

webmozart’s picture

We should then adopt the same model ourselves, for which the only question then is which classes/interfaces we tag @api or @internal.

For the record, my intentions when writing the policy were:

  • @api: This class/interface is really stable and part of the public API. Use it, implement it.
  • regular: This class/interface works out so far, but we might adapt it to some extent.
  • @internal: This class/interface might change drastically or even be removed. Don't touch.
webmozart’s picture

The policy has just been merged into our documentation repository. You can find the last version of the text on our website:
http://symfony.com/doc/current/contributing/code/bc.html

Thanks everybody for your helpful feedback! :)

Crell’s picture

Status: Active » Fixed

This was just a discussion thread and is long-since concluded.

Status: Fixed » Closed (fixed)

Automatically closed - issue fixed for 2 weeks with no activity.