[Review] Added detailed Backwards Compatibility Promise text

[webmozart]

I created a detailed text about which parts of the Symfony code are covered by our BC promise. The goals are to:

• tell our users which parts exactly are safe to use
• tell our contributors which changes they are allowed to do

I'll continue working on the individual rules of allowed changes. Nevertheless, let me hear your feedback.

Update (2014/01/10)

The draft is ready for review now.

[fabpot]

I would say 2.3 here as this is more accurate.

[webmozart]

Updated

[wouterj]

then this should also be merged into 2.3

[webmozart]

I will open another PR when everything else is finished.

[danez]

But "Add parameter with a default value" still breaks code if someone has overwritten the method in their class. Maybe also adding [1] here?

[webmozart]

You are right, thank you!

[richsage]

I would perhaps say "....comply with the rules" rather than "comply to". Either that or "adhere to".

[webmozart]

Thank you! Language suggestions are more than welcome.

[richsage]

typo: UPGRADE (apologies, I added this comment previously on an outdated diff)

[webmozart]

fixed

[fabpot]

@webmozart The document looks very good to me; I've made some comments about minor changes.

Thank you so much for taking time to thoroughly document what BC means for us. I'm very happy with the result and it will make discussion about future changes so much easier.

[webmozart]

Thanks @fabpot for the comments! I will adapt the document later today.

[webmozart]

@fabpot I adapted the document now. Any more feedback?

[cordoval]

3.0, etc.

[fabpot]

@webmozart Looks good to me

[weaverryan]

Nice work @webmozart - it reads very very well. And nice use of footnotes - I hadn't seen those before.

Cheers!

[webmozart]

Thanks for merging! :)

Who's in charge of doing the styling of the docs? The footnotes could use some love :) Also, it would be nice if the links would be rendered as superscripted numbers, like in books.

I just realized we need to discuss one more thing, namely the changing of method return values in regular classes/interfaces (but not in API classes/interfaces). The current version allows (among others) to change the return values of Symfony methods from:

Original Type	To New Type
array	instance of ArrayAccess, Traversable and Countable
ArrayAccess	array
Traversable	array
Countable	array

Contrary to the other changes listed in the table, these changes might break applications:

Examples (rule 1):

$array = $object->getFoo();

// fine if changed to an object
$array[1] = 'bar';
foreach ($array as $key => $value) { ... }
echo count($array);

// breaks if changed to an object
array_walk($array, 'callback');

// easy fix
$array = iterator_to_array($object->getFoo());
array_walk($array, 'callback');

Examples (rule 2):

$array = $object->getFoo();

// fine if changed to an array
$array[1] = 'bar';
echo $array[0];

// breaks if changed to an array
$array->offsetSet(1, 'baz');

// easy fix
$array = new \ArrayObject($object->getFoo());
$array->offsetSet(1, 'baz');

Rule 3 and 4 are basically identical to rule 2.

I originally allowed these changes because the upgrade path is so simple (iterator_to_array()/new \ArrayObject()), however do you agree with this?

A specific use case for these rules is symfony/symfony#9918.

[wouterj]

Who's in charge of doing the styling of the docs? The footnotes could use some love :) Also, it would be nice if the links would be rendered as superscripted numbers, like in books.

ping @javiereguiluz

[javiereguiluz]

@wouterj @webmozart I can take care of that. I'll return with more information when I know exactly when the new styles can be applied on the symfony.com website.

[webmozart]

Thanks @javiereguiluz! You're the best! :)

[javiereguiluz]

@wouterj @webmozart here it is the before/after comparison of the style of the footnotes. Please, tell me anything else that you'd like to change in this proposal and we'll see it in production soon:

[wouterj]

Thanks @javiereguiluz for involving us in the process! :)

I like it, while I think the numbers on the footnote (first image, (1,2,3,4...)) should be somewhat smaller too, they are not that important imo

[javiereguiluz]

@wouterj maybe we should hide those numbers? I don't know if they are useful at all. If you click on a footnote, there is no way to know which number you should go back.

[wouterj]

@javiereguiluz yes, that's an option too. But please note that if the footnote only applies to one occurence, the footnote number will be a link instead. I think it's harder to remove that one?

[javiereguiluz]

In the case of unique footnotes, we can disguise the footnote link simply by changing the font color.

[wouterj]

Ok, let's do that :) (and also add cursor:default; to remove the pointer cursor ;) )

[webmozart]

@javiereguiluz Awesome! Yes, I would like to hide the backlinks too ( (1,2,3,4,..) ) if that's possible with the RST parser. Is it possible to remove the squared brackets around the numbers?

[webmozart]

Also, could you change the table style so that the grey horizontal lines don't cut through the black border of the table? Should be possible by moving the black border from the cells to the table itself.

[javiereguiluz]

• The backlink numbers are now hidden.
• I've asked if we can remove the square brackets around footnote numbers, but I'm not very confident about being possible.
• Definitely the styles of the tables need to be fixed. I haven't done it yet because we are postponing those style changes for the upcoming symfony.com redesign (we will announce some things about this soon).

[webmozart]

Cool, thanks @javiereguiluz! I just realized that the fonts in the footnotes are very different. One is the font of the table content ([1]-[4]), the other is the one of the paragraphs in the normal page content ([5]-[6]). Is this waiting for the redesign too?

[javiereguiluz]

@webmozart you are right! Font normalization is going to be one of the biggest tasks for the redesign.

[wouterj]

@javiereguiluz you forgot to remove the link style for hover. You'll get a pointer cursor and an underline when hovering over the numbers in the footnotes.