Edit report at https://bugs.php.net/bug.php?id=77348&edit=1
ID: 77348
User updated by: chealer at gmail dot com
Reported by: chealer at gmail dot com
-Summary: Misleading Edit button (Experimental but not flagged
as such)
+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:
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.
Previous Comments:
------------------------------------------------------------------------
[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.
------------------------------------------------------------------------
[2018-12-26 23:38:29] cmb@php.net
I suppose these patches have not been swallowed by PhDOE, but
rather have been rejected, maybe because they have gone stale
(PdDOE apparently doesn't store diffs, but rather the complete
file, so if someone else edits the file, the presented patch often
makes no sense anymore). Also, we likely delete unsuitable
patches without any notice to submitters, since often it is not
possible to notify them.
> Make it less likely that contributors reach Php Docbook Online
> Editor from the documentation. Either remove the link, move it
> somewhere less prominent, or change the label ("Propose a change /
> Edit" would already be less misleading).
I think that we should remove the link altogether. A considerable
percentage of submitted patches are done by trolls who try to make
malicious or at least obviously bad changes. It's rather annoying
to check and delete these patches (if the latter is even allowed).
In the (hopefully not too) long run we should really switch to
Git[1] to be able to replace PhDOE with Github pull requests.
> After I submitted a proposal for prepare(), the Patches for
> review tab indicated "(0)". Yet, it contained stuff from more than
> 20 people.
Indeed, the count appears to be broken. However, I can't find
your patch regarding PDO::prepare, and there are currently only
submitted patches from eight people for the *English* language.
[1] <http://news.php.net/php.doc/969386622>
------------------------------------------------------------------------
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