Re: note 97852 modified in function.register-shutdown-function by visualmind

I hope you don't mind, Salah, but I'm going to CC the list with this as well, for future reference. On Wed, May 12, 2010 at 10:03, Salah Faya <visualmind@php.net> wrote: > Ops, sorry for that..  I thought you were doing that but it's my mistake not > paying enough attention.  I will try to do it right, and even apply it on > old notes as well.. but should I do that even for small lines of code? It's absolutely understandable, no worries. I would use your discretion for whether or not it's reasonable for adding the opening and closing tags. For functions and multi-line bits, I do, but I wouldn't if it was just a reference to the function name or a variable. For example, I would add the tags to this: function sample_function($varsAsArray,$varAsString) { foreach ($varsAsArray as $k => $v) { if ($v == $varAsString) $$k = $v; } } .... but not to this: $something = true; .... or this: The strstr() function is used like strstr($foo,$bar). > btw, I'm still kinda confused about the following cases, what is the correct > action (confirm please): > > 1- Valid notes submitted by anonymous  (no emails)  -> delete? If it's valid, no. It's good to keep the note regardless of who submitted it. > 2- Valid notes submitted by invalid email (just the name) -> keep? Yup. Those are keepers as well. > 3- Notes that appear to correct / or reply a previous note by others -> > delete and modify previous if possible? You got it. Historically, what I've done is to put a small addendum to the bottom of the note, in brackets, like so: [EDIT BY danbrown AT php DOT net: Contains a bugfix submitted by "Anonymous" on 12-MAY-2010 with the following note: "This fixes the typo in the variable name which caused the script to die."] > 4- Notes that talk about a workaround for what they think is a non-php > related bug  -> keep? Sure, workarounds are generally okay to keep. > 5- Notes that talk about a workaround for what they think is a > php/extension-related bug  -> keep? Yes, as long as they're not reporting it as a bug in the notes. If you think that's what they're doing - even if they provide a workaround - reject the note (if it's a valid email) or delete it (if it's not). If they complain by reply email, simply write back (and CC the notes list) that you felt it would be better as a bug submission sent to http://bugs.php.net/ to help make PHP better for the community. > 6- Notes that add something useful but look like duh-it's-obvious for others > -> delete? Heh. Yeah, that would be something to delete. Same as if it is a reinvention of the wheel. For example, the following example note would be deleted (not rejected): "I needed a way to extrapolate values from the HTTP GET array to work backwards-compatible with a script that used registered globals from our old host, so I wrote the following function: <?php function extrapolate() { global $_GET; foreach ($_GET as $k => $v) { global $$k; $$k = $v; } } ?> Then just call it as <?php extrapolate(); ?> with no parameters." That would be deleted for a number of reasons: bad code (no need to globalize $_GET), reinventing the wheel (as mentioned), and - one could argue - useless, and in the documentation. All in all, it would just be deleted for "other reasons" under the options we have now. > One other thing, how I can contribute beter.. I mean is it better to go > through the old notes (where do I start?) instead of just following the new > notes which you already are covering anyway. Or is there a special time of > day/week you suggest to focus on the new notes while you are away. I've done thousands of old notes, and keep up with them on a daily basis as they come in so that it doesn't get overwhelming. So as they come in, review and manage them if you have time. And as you go through the manual on your own, glance through the notes and see what can be fixed. I've done almost 11,000 notes, but trust me: there's still a lot of work to do. Some quick points to remember: REJECT the note if it contains a valid email address and .... .... it is reporting a bug in the documentation. .... it is reporting a bug in PHP. .... it is a request for assistance or a code review. .... it is any kind of question posed in a forum-like style. EDIT the note if.... .... it is missing opening and/or closing tags on a block of code. .... you notice an obvious typo (slp_autoload, for example, but be sure it's not a user-defined function first). .... it contains advertising of any form (e.g. - "Read the rest at my blog at http://blog.example.com/"). .... it would be better-suited on a different manual entry. Simply edit the field for the manual entry to move it. DELETE the note and EDIT a referred note (and include credit) if.... .... it points out a bug that would cause a user-submitted function to fail or otherwise not work as expected. .... it contains a typofix for something in the code, but NOT if it's just a typo in the user's comments. DELETE the note and DELETE a referred note if.... .... the newer note points out issues with code that you can verify by review, but doesn't offer a suggested fix. .... the newer note debunks the older note (e.g. - "Bob said in April that four is greater than six, which is not true!"). DELETE the note if.... .... it refers to another note on the site by number, date, author, or content, because if the referred note is deleted, this note becomes deprecated. .... it refers to a forum or other third-party site discussion, blog, et cetera. .... it has nothing to do with the manual page it was added, and doesn't seem to be worthwhile to relocate. .... it is SPAM. .... it is useless. .... it is a test post. .... it is a duplicate (remove the OLDEST one(s) and keep the NEWEST one). .... it simply points out that a bug report was filed. .... it meets the criteria for rejection, but does not include a valid email address. .... it "reinvents the wheel" by doing what a built-in function does, but IS NOT a workaround to add functionality to older versions of PHP. .... it is very similar or the same as an older note. .... it appears as a "forum" post, whereby it appears to be part of a discussion and/or inciting or encouraging a discussion to take place in the notes. .... it refers to functionality or issues with PHP that have changed, and does not mention a specific version. .... it contains strictly PHP3 or PHP4 code. .... it is just another note pointing out the obvious, like an installation note such as "the Fedora way works on CentOS, too." .... it is a note that supposedly "improves" example code, or extends functionality. .... it is a note that simply gives benchmarks, unless, at your discretion, you feel the benchmarks are useful. .... you simply feel it does not add value to the php.net documentation, for any other reason. -- </Daniel P. Brown> daniel.brown@parasane.net || danbrown@php.net http://www.parasane.net/ || http://www.pilotpig.net/ We now offer SAME-DAY SETUP on a new line of servers!