PEAR software design policy

Dear All, I am currently working on the package 'Date' and I have a couple of design decisions with which I wanted to comply with the PEAR design policy: There are 3 functions setDay(), setMonth() and setYear() which can be used to set the individual parts of the date, or the user can set the date using setDate(), passing in a valid ISO-compatible string. The current behaviour of setMonth() etc. was to check that the month was between 1 and 12, and if not, to quietly set the month to 1. So if you try to set the date to 31st February then the class allows you to do this, so I wanted to change the behaviour of setMonth() to return an exception instead, because this date is obviously not valid. However it is possible that code exists that calls setMonth(2) then setDay(28), which would set a valid date, but by setting the object to a possibly invalid date between the two calls. Now should I allow an invalid date like this for the sake of backwards compatibility, or can I change this behaviour for the benefit of the users that this will not affect? I would also provide the function setDayMonthYear() which would allow users to write equivalent code. I don't think it will affect a lot of people, and it would be a rare occurrence anyway, but then how strict does backwards-compatibility have to be? My next question is that there is a function getJulianDate() which returns the day of the year from 1 to 366. But on Wikipedia it says that the 'Julian Date' is the no of days since Monday, 1st January 4713 B.C. This behaviour is in fact implemented by the function Date_Calc::dateToDays() (it does not actually document this fact, and the function is not valid for years < 0 anyway, but you can take my word for it). My thinking is that there is no point having all these functions unless they are well-documented, and even if they are well-documented, no-one is going to read ALL the documentation. And a crucial part of the documentation is the function name itself. So do we have to maintain perpetual backwards-compatibility (by providing aliases like 'getRealJulianDate()' and leaving the old functions alone), or is it possible to rename these functions? If anybody could help me with this I would be very grateful, Charles --------------------------------- Yahoo! Answers - Get better answers from someone who knows. Tryit now.