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
Comment #1
Crell CreditAttribution: Crell commentedComment #2
msonnabaum CreditAttribution: msonnabaum commentedTo 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.
Comment #3
webmozart CreditAttribution: webmozart commentedA 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).
Comment #4
rcross CreditAttribution: rcross commentedperhaps its just semantics, but I think the way that is worded is off-putting.
A possible improvement:
Comment #5
catchThis 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.
Comment #6
cdnsteve CreditAttribution: cdnsteve commentedMy 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.
Comment #7
Garrett Albright CreditAttribution: Garrett Albright commentedThank 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?"
Comment #8
Crell CreditAttribution: Crell commentedComment #9
webmozart CreditAttribution: webmozart commentedThanks 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.
Comment #10
webmozart CreditAttribution: webmozart commentedI simplified the description some more. Hopefully this will remove some of the confusion:
https://github.com/bschussek/symfony-docs/commit/8c6c7bf5b31a4cadde04fbf...
Comment #11
cdnsteve CreditAttribution: cdnsteve commentedI 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.
Comment #12
cordoval CreditAttribution: cordoval commented@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.
Comment #13
Crell CreditAttribution: Crell commentedI'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.
Comment #14
webmozart CreditAttribution: webmozart commentedFor the record, my intentions when writing the policy were:
Comment #15
webmozart CreditAttribution: webmozart commentedThe 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! :)
Comment #16
Crell CreditAttribution: Crell at Palantir.net commentedThis was just a discussion thread and is long-since concluded.