@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.

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

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

@webmozart Looks good to me

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

Cheers!

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 inregular classes/interfaces (but not in API classes/interfaces). The current version allows (among others) to change the return values of Symfony methods from:

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

Examples (rule 1):

$array =$object->getFoo();// fine if changed to an object$array[1] ='bar';foreach ($arrayas$key =>$value) {... }echocount($array);// breaks if changed to an objectarray_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 issymfony/symfony#9918.

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

@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.

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

@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:

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

@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.

@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?

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

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

@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?

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.

• 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).

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?

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

@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.