Bug #77348 [Opn]: Misleading Edit button (edition not immediate)

Edit report at https://bugs.php.net/bug.php?id=77348&edit=1 ID: 77348 Updated by: cmb@php.net Reported by: chealer at gmail dot com Summary: Misleading Edit button (edition not immediate) Status: Open Type: Bug Package: Online Doc Editor problem PHP Version: Irrelevant Block user comment: N Private report: N New Comment: > After, I completed each step to submit a patch against > PDO::prepare(). I can now see that my changes are reflected in the > actual documentation: In practise, it is not really relevant whether a patch is listed as work in progress, or whether it has been submitted as patch for review. In both cases somebody with sufficient karma will have to review the patch, and commit or reject it. Previous Comments: ------------------------------------------------------------------------ [2019-01-02 06:13:55] chealer at gmail dot com Thanks to much luck, just after reporting this I was pointed to a tutorial about using Php Docbook Online Editor, which explains the step I must have been missing: https://www.youtube.com/watch?v=HLAuzZh2GVo This tutorial is in French. After, I completed each step to submit a patch against PDO::prepare(). I can now see that my changes are reflected in the actual documentation: http://svn.php.net/viewvc/phpdoc/en/trunk/reference/pdo/pdo/prepare.xml?r1=337261&r2=346459 This process still appears to be limited as the submitter's name and change description appear to be lost, but given that it works and is quite straightforward, I apologize for describing the tool as experimental. I would rather argue that offering a save button (with the floppy disk icon) combined with the label "Edit" and without instructions when a contributor saves is likely to mislead, but that's a much less severe issue. I recommend to: 1. Relabel "Edit" to "Propose a change / Edit" 2. Make Php Docbook Online Editor's behavior or interface reflect that the edition process has 2 phases. This could be done by either warning each user on their first use, or by requiring users to perform a "Start a patch" action before editing files, so they realize what they are editing are temporary files only meant to generate a patch. ------------------------------------------------------------------------ [2018-12-27 14:10:00] cmb@php.net Back to the issue at hand: the relevant line that would have to be changed or removed is <https://github.com/php/web-php/blob/bda2d837724d59efe8580b9232d6d60fa545cf5b/include/shared-manual.inc#L448> ------------------------------------------------------------------------ [2018-12-27 11:32:57] cmb@php.net > The last proposal I made was in 2016, […] Ah, I see. Basically, I think the patch is fine, but I would use “template” only when referring to the $statement parameter. See the attached patch pdo-prepare. > The question is where it shows. I'm afraid, nowhere. > […] but there is something wrong in the system as a whole (the > engine plus its operators) […] ACK. However, I don't think we should spend much time on improving PhDOE, given that there are way more suitable alternatives *almost* readily available, such as Github pull requests. Personally, I even prefer to have a bug report with an attached patch instead of a submission to PhDOE, unless it's about a simple typo fix or such. While this is slightly more work, it allows to discuss the patches and to track the progress. ------------------------------------------------------------------------ [2018-12-27 11:32:49] cmb@php.net The following patch has been added/updated: Patch Name: pdo-prepare Revision: 1545910369 URL: https://bugs.php.net/patch-display.php?bug=77348&patch=pdo-prepare&revision=1545910369 ------------------------------------------------------------------------ [2018-12-27 04:06:08] chealer at gmail dot com Thank you for checking cmb. The last proposal I made was in 2016, so it is expected that it doesn't show in the Patches for review tab. The question is where it shows. I am not saying that reviewers are mishandling proposals, but there is something wrong in the system as a whole (the engine plus its operators) if the end result is that people who logged in and did not refuse to provide any contact information end up not being notified of rejections. And really wrong if even by returning to the website they can't figure out who rejected, when or why. ------------------------------------------------------------------------ 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 https://bugs.php.net/bug.php?id=77348 -- Edit this bug report at https://bugs.php.net/bug.php?id=77348&edit=1