#50218 [Opn]: flock() has numerous documentation errors

ID: 50218 User updated by: shelby at coolpage dot com Reported By: shelby at coolpage dot com Status: Open Bug Type: Documentation problem Operating System: All PHP Version: 5.3.0 New Comment: Yes exactly people become jaded by the open source process when it gets bogged down in politics. I do not have time to go locate that manual annotation submission policy page again, but perhaps I can suggest something: "Manual annotations should _ONLY_ be used to supplement the understanding of, and experiences with, the official manual text. When the official manual text is in error, _INSTEAD_ please submit a documentation error bug report at bugs.php.net. When submitting a documentation error bug report, please do not also submit a manual annotation, because this creates duplication of effort and confusion for us and the PHP community. Although perfection is not promised, we make best efforts to process documentation error bug reports within 72 working hours, and to apply any accepted change to the mirrors of the official manual text within days." Also let me suggest you add a feature where people can mark bug reports as applicable to certain manual pages, then have a scrollable list of cross-references on both the manual pages and the bug reports. Formalize the cross-reference at the DB level, may improve utility and understanding. Previous Comments: ------------------------------------------------------------------------ [2009-11-19 12:18:26] shelby at coolpage dot com One reason the documentation of PHP's flock() is critical, is for example in my PHP-GTK2 application (a internet cafe timer that is run on customer logon), I need some way to let only one instance of the application run at a time (if customer attempts to run more instances), but I don't want the other application instances blocking-- rather I want them to exit immediately when they detect the lock on the shared file. So the fact that LOCK_NB is supported on Windows is critical to my application (since I am targetting Windows now, but want *nix OS an option in future). Also since many people do run on FreeBSD (e.g. my pair.com server account), it is important to know that the underlying OS fcntl implementation, is going to behave incorrectly if the same process does fclose() while also holding a lock on the same file with another file handle. In fact, that might not be considered a documentation bug, but a real bug where flock(2) instead needs to be used on FreeBSD (and any system implementing the "stupid" Posix.1 standard for fcntl). Thanks for the invitation to become more involved with PHP, actually I have been contributing infrequent suggestions and bug reports (and a few manual annotations) since as far back as PHP3 and I think I've interacted with rasmus and sniper roughly 6 or 7 years. I think I was pointing out the need for destructors and other OO features back then. I remember making a report about the impossibility of reporting error state through JSON due to the way the older PHP had lost its state by the time the error handler got called. In any case, I've got my fingers in many pies right now, e.g. I recently delved into functional programming and tried to simplify it: http://www.coolpage.com/commentary/economic/shelby/Functional_Programming_Essence.html (especially see how I reduced Category Theory and Monads from 10+ pages of goobly-gook mind bending to something easy to grasp by any programmer) And within 2 weeks of starting to learn it, made a crucial suggestion that was accepted by one of the co-creators of Haskell: http://hackage.haskell.org/trac/ghc/ticket/3630 Right now, my focus is on trying to move more free lance (less corporate control) programming into developing world, and so I am in extreme rush because I do not feel we have much time, so my passion is driven also by survival of mankind and freedom and general, so that might explain why I am bit touchy and why I take any opportunity I can get to tell people and recruit more to the awareness (I need to calm down for the long-haul, but reading the links about H1N1 may shed some light on my sentiments): http://goldwetrust.up-with.com/precious-metals-f6/silver-as-an-investment-t33-210.htm#2342 http://www.financialsense.com/fsu/editorials/2009/1109.html Apologies to everyone for this over-personalized diatribe, and again my apologies for misunderstanding the intent and timing of your policy. Thanks for being receptive to making your manual annotation policy more clear. And I do hope this bug report was accurate and helpful. You guys (any gals?) can determine that. All the best. We will cross paths more. ------------------------------------------------------------------------ [2009-11-18 17:10:03] danbrown@php.net That's a fair assessment, and one that should be addressed. We constantly update the site based on suggestions from users in situations that, in all honesty, we may not foresee as part of the big picture. This is an open source project that evolves minute-by- minute, most often with suggestions and submissions by folks such as yourself being implemented over time. Our documentation team is pretty snappy at getting things accomplished quickly, and we're lucky (at least so far) that we don't face bureaucratic roadblocks like a lot of other projects can't seem to overcome. It's by no means a guarantee that the bug will be fixed within 72 hours, but there's a better chance that it will than it won't. That aside, you seriously may want to consider joining the project. You're obviously passionate about it.... why not apply that directly without having to go through a middle-man to achieve results? With no word in jest or sarcasm, the PHP project could benefit from your help. ------------------------------------------------------------------------ [2009-11-18 17:00:26] shelby at coolpage dot com If it is true that documentation errors are resolved within 72 hours, then I eat my words and humbly apologize to you. If you simply added that statement-of-fact to the policy page and to the rejection email, then I wouldn't have even bothered adding the note to the manual page. I do not understand why you wouldn't make that clear on the policy, so that people will not feel like they have fallen in a blackhole, as can be the case in other social politics. Again if that is the case, my apologies. I was offended, because I have had my effort wasted too many times in past and it is unusual to see bug reports resolved all the way to release within 72 hours. I think it wasn't abnormal for me to assume otherwise. Please consider clarifying your policy page, so that bad feelings can not forment from misunderstandings. I can not read your mind. You have to state it. ------------------------------------------------------------------------ [2009-11-18 16:49:00] danbrown@php.net == KEY: > Your Comments My Responses == > In the meantime, you have many errors in > those user comments which did get approved > on that page. Talk about future housekeeping! Tell me about it! It's an ongoing effort, and one in which we'd certainly welcome the assistance of someone with as much time available as you're demonstrating in noticing the errors. We're all volunteers who donate our time to the community on a daily basis, and if you'd like to join the ranks to offer your assistance in making things better for your fellow PHP developers, it would be greatly appreciated! > Dan you have no point and no logic. But you > are good at destroying effort and chasing > away the people who do apply inspired effort. Aww, when you say it, it hurts. ------------------------------------------------------------------------ [2009-11-18 16:45:35] danbrown@php.net == KEY: > Your Comments My Responses == > Dan Brown I had already read the submission > guidelines for manual annotations, and in > fact my notation repeats some of the other > notations already on the manual page (e.g. > that LOCK_NB is a binary flag option that > can be combined with options). > > Removing my note from the manual page, > means that others will spend a whole > day of frustration trying to figure > out what I figured out, for as long as > the manual is not fixed, which who > knows might be months or even years. Not true. When a documentation bug is submitted, it is usually resolved within 72 hours. So until you know for a fact how the timing and patterns work, either join the project or don't make assumptions in how we operate, or question why we do things the way we do, thanks. > So you preference is to deny the users > the information, because they surely > won't find this bug report in meantime? My preference is to maintain a good, solid reliable presentation, and not to confuse others with conflicting or redundant information. When a documentation bug is fixed, it's not normal procedure to then sift through every annotation on the corresponding manual entry to ensure that we've updated it. One could only imagine the effort that would take. However, your estimation as to the intelligence of your peers and their ineptitude at tracking down relevant information is interesting to me. Have you frequently found yourself in situations where you are the only one with enough sense to help yourself? If you pass judgment as to the ability of those around you, my guess is that you'd find yourself quite lonely in many circles. > I put a link here in the bug report, so > who ever fixes the bug, can send an email > to the note editor to remove my note later. Links don't work that way, Shelby. They direct you TO a page, they do not report back FROM the target. So this is baseless. > Your premature deletion of my note did not > save any housekeeping effort on your part, > it merely destroys my work and hides the > information from the millions of PHP users. It was not premature, and in fact did serve its purpose in housekeeping. Further, please check your metrics, as "millions of PHP users" would be fantastic, but I think may be a bit exaggerated in this case. > Shame on you Dan Brown. At least you > had the dignity to post here what you > had done, so I can reply to you. Dignity is the one thing I didn't have to sacrifice on my wedding day. Now, if we were to discuss other things like personal space or sanity.... > Waste my time once, but never again. I > will withhold my contributions from PHP > from here out. It's worth noting that, within a few moments, you posted a follow-up on this report. Perhaps you meant this promise to be appended to the end of that message. > Congratulations. Thank you. It's been a long, difficult journey, but we appreciate your support. We'd like to thank the Academy.... ------------------------------------------------------------------------ The remainder of the comments for this report are too long. To view the rest of the comments, please view the bug report online at http://bugs.php.net/50218 -- Edit this bug report at http://bugs.php.net/?id=50218&edit=1