Resurrecting the Function Renaming Thread

Hello All, I would like to resurrect the Function Naming thread that puttered out around New Years Day. After reviewing the messages, it seemed that we were quite close to a group consensus on what to do. I would guess that the holidays threw everyone's schedule off a bit. :) I have gone through the messages and attempted to summarize the thread. Hopefully, this summary will get the effort back on track again. Note, if we can agree on a solution, I will start implementing it immediately. (Why immediately? Well, my publisher has been nice enough to make some allowances so that I can work on PHP stuff - however, their niceness will only last me about a month. :) Function Renaming Summary ######################### Important Notes ######################### I have chopped a lot of content out of the thread - if anyone notices something important that I have missed, please post the omission. Thanks! Also, the suggestions are *my* summaries of what the original author suggested - review the complete message to ensure that you fully understand what the author was suggesting. ######################### First, the items that we agree on: Should we rename existing functions to follow a standard format? ================================================================ IIRC, everyone agreed on this point. The only concern what how it could best be accomplished. What is the preferred naming style? =================================== The preferred format for function names has been defined for quite some time. It can be reviewed at http://cvs.php.net/viewcvs.cgi/phpdoc/README?rev=1.9&content-type=text/vnd.v iewcvs-markup Next, the simple questions left over from the thread: Do we have a list of bad function names? ======================================== James was working on this list - at last report, it was about 1/2 finished - is it any closer to being completed? James, do you need someone else to pick it up for you? Is there a performance hit for having lots of function aliases? =============================================================== Will there be any noticeable decrease in performance if we have a 4 or 5 hundred active aliases? Will this have any other non-obvious side effects? And finally, the various solutions that were suggested: Ron Chmara ---------- Summary of earlier discussions on the phpdoc list: 1. Deprecate early, deprecate hard, cut out the old one entirely. 2. Age it out gracefully, somehow. The "how" wasn't clearly defined. 3. De-document it, but leave it usable, possibly forever. See the complete post at: http://marc.theaimsgroup.com/?l=php-qa&m=97728683829899&w=2 Add a php.ini directive that manages warnings for deprecated aliases: obsolete_warnings=on|off [on=default] With the deprecated function name/alias/usage invoking a warning macro, one (major/minor/mini) version prior. See the complete post at: http://marc.theaimsgroup.com/?l=php-qa&m=97802947403309&w=2 Try to use existing systems for handling aliases and deprecation, rather than building and learning new ones. Add two macros for deprecated aliases: PHP_OLDFALIAS_NOTICE PHP_OLDFALIAS_WARNING Use comments (or CVS) for what revision/date the change happened. Delete old aliases later, as the developers are available. See complete message at: http://marc.theaimsgroup.com/?l=php-qa&m=97847164731536&w=2 James Moore ----------- Use a version specific macro to alias deprecated aliases. PHP_ALIAS_404_DEPRECIATED(function_name) The version number contained in the macro name would control how the alias would throw errors. See the complete post at: http://marc.theaimsgroup.com/?l=php-qa&m=97800463220007&w=2 Richard Lynch ------------- Phase I 1. Documentation notes both function names, clearly marking the deprecated one, with a link to a page describing the scheduled changes and list of functions to change. 2. Both functions work with no warning/error/etc Phase II, at least 2 or 3 minor revisions later 1. Documentation notes both function names, clearly marking the deprecated one with a note about the warning message, and the same link as above. Perhaps error messages should include a link to additional information on the deprecation process. 2. Deprecated function issues the lowest level Warning possible. Phase III and following, at least 2 or 3 minor revisions after previous Phase Same as above, but one level higher in the error system. Final Phase -- The deprecated function should remain in the manual another 2 or 3 revisions, and finally be phased out. The *new* function names should continue to point to the page describing the changes that occurred and list of functions that changed at least through and including the next *major* revision. See the complete post at: http://marc.theaimsgroup.com/?l=php-qa&m=97802549627858&w=2 Zeev Suraski ------------ Deprecated function aliases should be phased out very slowly. Additionally, the deprecation of old aliases should not be the impetus for a release. See the complete post at: http://marc.theaimsgroup.com/?l=php-qa&m=97803294210823&w=2 --zak