Re: QF3.2 - 2 BC breaks with custom method!

Hi Alexey/Lukas, Moving this to pear-dev for new discussion idea. Alexey Borzov wrote:

Hi! Lukas Smith wrote:

The problem with your approach is: QuickForm's validation was designed to validate the *value*, not the *element*.

Just as a quick FYI without knowing any of the details: Having complete docs for packages helps for deciding what a BC break is and what isn't. Removing undocumented features is not a BC break!

Tend to agree here... Nowhere in QuickForm docs/examples it is advised to extend the QuickForm class and to add validation methods that access the object's properties. This solution is fragile and obviously will have problems surviving major validation refactoring.

This is exactly the main reason why documentation is so crucial - it's not entirely for users to figure things out, but if you document things as experimental, or don't document them at all, it gives you a really valid excuse when users who have used them complain :). Quickform is a perfect example of a well-documented package where a BC break is not an issue for the majority of the users, and is handled easily with the few who refuse to read carefully. New idea: It would be useful to perhaps add a <bc> section to the package.xml, in which it is possible to document (like <provides>) what has been removed from the API or changed. This would best not be auto-generated, but it would be possible for PEAR_PackageFileManager to do this using the doc tags and a docblock parser. I'll play around with this idea and see if I can come up with something that takes all the potential issues into account. This would allow easy documentation of BC breaks inside the release, allowing people to determine prior to upgrading what effect might occur upon their application. It would be most helpful if there was some way of specifying the API inside package.xml which is more intelligent than <provides>, so I will be thinking about this to see if there is some cool way of doing this. Regards, Greg