php.net |  support |  documentation |  report a bug |  advanced search |  search howto |  statistics |  random bug |  login
Bug #81290 Documentation pages: Confusing and unclear "Submit a Pull Request" link
Submitted: 2021-07-25 13:37 UTC Modified: -
From: chealer at gmail dot com Assigned:
Status: Open Package: Website problem
PHP Version: Irrelevant OS:
Private report: No CVE-ID: None
View Developer Edit
Welcome! If you don't have a Git account, you can't do anything here.
If you reported this bug, you can edit this bug over here.
(description)
Block user comment
Status: Assign to:
Package:
Bug Type:
Summary:
From: chealer at gmail dot com
New email:
PHP Version: OS:

 

 [2021-07-25 13:37 UTC] chealer at gmail dot com
Description:
------------
A while ago, I reported bug #77348, about the misleading Edit button which then linked to the not-so-famous "Php Docbook Online Editor".

I'm happy to see PHP documentation pages no longer rely on "Php Docbook Online Editor". I'm also happy to see pages no longer have a misleading "Edit" link which only allows to propose changes.

Unfortunately, its replacement is quite confusing, and is unclear. The link which replaces "Edit", to the left of the "Report a Bug" link at the top of pages like https://www.php.net/manual/en/pdo.prepare.php, is a link to https://github.com/php/doc-en labelled "Submit a Pull Request".

Presumably, a contributor would be expected to do something like the following:
1. Create an account on the GitHub website and login
2. Create a Git branch dedicated to his proposal
3. Figure out which file needs to be modified
4. Modify the file
5. "Submit a Pull Request", a cryptic way to say the contributor must conclude by offering his changes, which is technically a *request* for a PHP developer with the necessary credentials to "pull" (Git jargon) the contributor's branch and merge its changes in the repository.

This label is obviously high in jargon, but there is a reason for that: a proper label on that same link would surely leave contributors even more confused about what they'd need to do.

Therefore, I recommend to:
1. Link instead to a page documenting how a change may be performed or proposed
2. Switch to a functional and vendor-neutral label (like "Propose a change / Edit", proposed in #77348)


Patches

Pull Requests

History

AllCommentsChangesGit/SVN commitsRelated reports
 
PHP Copyright © 2001-2024 The PHP Group
All rights reserved.
Last updated: Sat Oct 05 07:01:27 2024 UTC