Support for Drupal 7 is ending on 5 January 2025—it’s time to migrate to Drupal 10! Learn about the many benefits of Drupal 10 and find migration tools in our resource center.Problem/Motivation
When you finish installing Drupal (at least, with Standard profile but I expect it is universal), you get this message:
All necessary changes to sites/default and sites/default/settings.php have been made, so you should remove write permissions to them now in order to avoid security risks. If you are unsure how to do so, consult the online handbook.
There are similar messages generated elsewhere in the installation process too, if you don't have the right file permissions for the install.
The problems with this:
a) In our hook_help() we are not using the phrase "online handbook" any more. We use the term "online documentation". This is never called "handbook" on drupal.org and should not be referred to this way, hasn't been for years.
b) This is not good link text for accessibility, because it doesn't tell you where it goes.
c) The link goes to this page:
https://www.drupal.org/server-permissions
which is actually a page called "Webhosting issues". That page does not tell you how to change file permissions.
d) We don't actually have a page on drupal.org about changing file permissions, and how you would do that depends a lot on whether you have shell access, what O/S you're on, what hosting you have, etc. Generally we want our documentation to document Drupal anyway, not O/S and hosting stuff. Plus our documentation is only in English. So, even making a link here at all is problematic.
Proposed resolution
Since we do not have an appropriate place to link to, we should take out the "If you are unsure..." sentence from this message and other ones in the installation process that are currently linking to the irrelevant page. The idea would be someone gets this message, which gets across the point that they need to change file permissions, and they would then go to Google or their hosting FAQ and figure out the appropriate way to fix the permissions, rather than us first sending them to an irrelevant page in English on Durpal.org that won't answer that question.
Remaining tasks
Make a patch.
User interface changes
We won't give people irrelevant links in install messages.
API changes
No.
Data model changes
No.
Beta phase evaluation
| Issue category | Bug because we're sending people to an incorrect page |
|---|---|
| Issue priority | Major because it's part of the install process and is confusing |
| Unfrozen changes | Unfrozen because it only changes strings |
| Prioritized changes | The main goal of this issue is usability and it is a bug fix |
| Disruption | None. |
Comments
Comment #1
mikebarkas CreditAttribution: mikebarkas as a volunteer commentedI will work on this to remove the "If you are unsure..." sentence.
I am a novice and could use some exercise.
Comment #2
harjotsingh CreditAttribution: harjotsingh as a volunteer commentedThe page at https://www.drupal.org/server-permissions deals with all issues that are faced after installation.
It contains the links to the documentation about permissions on various operating systems.
Links are :
Brief intro to Unix file permissions:- https://www.drupal.org/node/34023
Modifying Linux, Unix, and Mac file permissions:- https://www.drupal.org/node/202483
Modifying Windows file permissions:- https://www.drupal.org/node/202491
The message after installation needs to be changed to :
All necessary changes to sites/default and sites/default/settings.php have been made, so you should remove write permissions to them now in order to avoid security risks. If you are having issues, consult the online handbook.
Comment #3
longwaveNo patch to review.
Comment #4
jhodgdonOK. We do not want it to say "online handbook".
The link text should describe the page it is going to, like "online documentation page for xyz". Also we no longer use the term "handbook" for the online documentation. Thanks!
By the way, the reason I marked this "major" is it is the first thing people see after they install.
Also, I kind of disagree that this is a good page to link to. I think we shouldn't even have all this stuff about Unix file permissions -- why repeat this on drupal.org? It's not about Drupal, and there are better docs elsewhere, and people will have to figure out which of the 20 pages below there is the one that will solve their problem (if they don't know about file permissions, they may not even know what O/S they are hosted on).
Comment #5
xlin CreditAttribution: xlin commented@jhodgdon, how about this documentation page? https://www.drupal.org/node/2543580
Comment #6
xlin CreditAttribution: xlin as a volunteer commentedUpdate Post-install message and link to following.
All necessary changes to sites/default and sites/default/settings.php have been made, so you should remove write permissions to them now in order to avoid security risks. If you are unsure how to do so, consult the online documentation page on changing file permissions.
Comment #7
mikebarkas CreditAttribution: mikebarkas as a volunteer commentedComment #8
harjotsingh CreditAttribution: harjotsingh as a volunteer commented@xq1003
We do not want to change it to "online documentation page" as it doesn't describe what the page is for also the page linked is about Webhosting issues which contains all issues but is not a dedicated permissions page.
We should either change the text to "website issues page" or we can change the link so that it goes to one of the documentation about permissions page.
I changed the link to :https://www.drupal.org/node/244924
Comment #9
xlin CreditAttribution: xlin as a volunteer commented@harjotsingh @jhodgdon
Wrong link was used in the patch. The correct link that I'm thinking is https://www.drupal.org/node/540242
Comment #10
jhodgdonThanks for the patches and discussions!
So the text in the latest patch seems OK except it says "the the":
However, I am not sure about linking to
https://www.drupal.org/node/540242
That page is not accurate. It says that the install script changes the permissions. If that were the case, this message would not be shown.
Also, the link text says it is "the online documentation page on changing file permissions", but really that's a small part of the page, so maybe if you're going to use that link (and maybe edit the page so it is more accurate), it should say "the online documentation page about the settings file and permissions"?
And really, someone who doesn't know how to change file permissions is not really going to figure out how to do it by reading this page...
So, again, I really think we should just take this sentence with the link out. We're telling them they need to update the file permissions. They can do a web search, check their hosting knowledge base, or read the help for the file transfer software they are using to figure out how to do this.
Comment #11
harjotsingh CreditAttribution: harjotsingh as a volunteer commentedWe can remove the text and link because the installation guide has the section in Step3 which covers the Permissions after Installation.
But wouldn't that make it uneasy for users ?
Comment #12
harjotsingh CreditAttribution: harjotsingh as a volunteer commentedThe patch after removing the link and text.
Comment #13
jhodgdonWell, the problem is that we do not really have a comprehensive page on drupal.org that really explains all the possible cases of how to change file permissions. Nor do I think we should have one -- there are a ton of ways depending on your operating system, hosting control panel, whether you have shell access, etc.
My feeling is that people who don't know how to change file permissions, if they go to the proposed link, will just get confused. So I do not think this is beneficial to send them there. If instead we just tell them "you need to change the file permissions", if they don't know how, they will seek out that information for their set-up and hopefully find it. This is I think better than sending them to a link that doesn't provide that information.
Also that link is only even mildly OK for people who can read English, which is by far not the entire world.
So... that last patch takes out the entire message. All we want to remove is the part that says "If you are unsure how...".
Comment #15
xlin CreditAttribution: xlin as a volunteer commented@jhodgdon, thanks for clarify. I update the patch with the link removed. Should a page be create on d.o to explain this as a sub-task?
Comment #16
xlin CreditAttribution: xlin as a volunteer commentedComment #17
longwaveThe same link (or a very similar one) appears in several other places. Do we need followup issues to change or remove this in those places as well?
core/includes/install.core.inc (5 instances)
core/includes/install.inc (1 instance)
core/modules/system/system.install (1 instance)
Comment #18
jhodgdonSeems like we should do them all here, rather than having a bunch of similar issues with similar patches? Thanks!
And the latest patch looks good to me.
Comment #19
harjotsingh CreditAttribution: harjotsingh as a volunteer commentedPatch Updated
Comment #21
harjotsingh CreditAttribution: harjotsingh as a volunteer commentedSorry for the last patch
Comment #22
longwaveThis covers the 7 extra messages I mentioned in #17. One of these also mentioned INSTALL.txt, and I checked in there - we do have some instructions in there about using chmod commands to alter permissions. Not sure if we should refer to this file, or alter these instructions as well, or leave that for now as being out of scope.
Comment #23
jhodgdonThese all look fine to me. Thanks for the patch!
Updating summary...
Comment #24
alexpottAre we really sure about this change? If you have installation problems https://www.drupal.org/server-permissions is a pretty great place to land. And searching d.o for help can be frustrating.
Comment #25
jhodgdonI disagree that this is a good place to land for this specific problem. This message is only about "it's time to change the permissions on your settings.php file", and that page doesn't tell you how to do this, for most people, as far as I can tell. Plus, it's in English, which is OK only for a subset of people. The pages underneath don't either, really.
Comment #26
alexpottI'm not comfortable committing this patch - it removes all links to https://www.drupal.org/files/issues/2543580-remove-handbook-links-22.patch from the installer. This handbook page has gathered together years of knowledge on getting Drupal to work in different hosting environments and it seems pertinent and good to point people to it if they are having problems installing. Tagging for product manager review and assigning to @webchick.
Comment #27
jhodgdonThe current message says:
So this link is purporting to be a link to how to remove write permissions. The link does not give you that information.
I also don't think that most people who install Drupal are going to find a lot of useful things there, and why link there rather than many other pages on Drupal.org that might be more relevant to most users who install Drupal, like something that actually gets them started administering their site?
And furthermore this page is only available in English. Fine for us, but...
Comment #28
webchickYeah, sorry, I can't really really get on board with leaving people up shit creek without a paddle, especially in their first 30 seconds of using Drupal.
I'd rather approach this from re-wording the error message so that when they land on https://www.drupal.org/server-permissions they are getting what they expect. The fact that the page is in English only is true of all handbook references, which are littered all over the place in core, so not sure why that would be a reason to remove the reference to the page.
Suggested rewording: change from
to:
...or something like that.
And, probably even better, make a new page at https://www.drupal.org/webhost-issues that contains the current contents, and restore the old content of https://www.drupal.org/server-permissions (as a child) so that the URL actually does what it says. :P
Comment #29
jhodgdonI still think that trying to write a page that covers, for all possible servers and hosting control panels and operating systems, how to modify file permissions, is a losing battle. I seriously would rather leave them without a paddle so that they don't waste their time trying to read a page that quite likely isn't going to cover what they need in the detail they might need, and let them go directly to a web search or contacting their hosting company, rather than pointing them to a page that will never cover all the possibilities.
And... Where is this old content that we need to restore, exactly?
Regarding all the links to drupal.org in Core, yeah, it's a big problem. This issue illustrates the problem nicely... and the related problem that since anyone can edit these pages at any time, we inevitably end up with some of the pages being edited into something else (like this one is), or even deleted or unpublished.
Comment #30
webchickhttps://www.drupal.org/node/202483 (a child page of that) looks like the content I would expect from the URL. Not sure if it was originally part of that or not, but a URL called server-permissions I would expect to link to something about server permissions, not an overview page about webhost stuff.
Comment #31
jhodgdonYeah and there's a separate page for Windows right next to it in the outline. Not sure what to do.
Comment #32
ifrikComment #33
kjay CreditAttribution: kjay commentedI am working on this at the mentored sprint at Barcelona 2015. My mentor is jp.stacey. I'm going to write a patch with the text and link for approval, as per https://www.drupal.org/contributor-tasks/create-patch
Comment #34
kjay CreditAttribution: kjay commentedHere's a patch that follows the text webchick suggested in comment 28 but doesn't go to the extent of changing the URL we're linking to as this seems to need more discussion on what to do drupal.org side.
It does seem odd that the URL for the current target page https://www.drupal.org/server-permissions hits a page titled more generically as 'Webhosting issues'. I think it could make sense to change the current page at https://www.drupal.org/server-permissions to have the url https://www.drupal.org/webhosting-issues and optionally to update this patch so that it points at the new url. This will effectively push the responsibility for providing a good user journey for finding help on this and other issues over to the drupal.org landing page. The wording in this patch implies this anyway and is probably the more future proof option.
Anyway, patch attached for comment and I think the changes need to be on drupal.org will need further discussion and can we keep them separate?
Comment #35
kjay CreditAttribution: kjay commentedComment #37
kjay CreditAttribution: kjay commentedRedoing my work.
Comment #38
rumburak CreditAttribution: rumburak as a volunteer commentedI think the changes in the patch done by kjay are fine. I think it is better to link to the page https://www.drupal.org/server-permissions than to remove completely the link.
Comment #40
jhodgdonThis looks good to me, and I think that the objections made to earlier patches have been satisfied. Nice work! Thanks!
Comment #41
alexpottThis looks like a good solution. Committed 82198fe and pushed to 8.0.x. Thanks!
Comment #44
kay_v CreditAttribution: kay_v as a volunteer commentedBrief note to self to review this issue and cogitate on next steps. In Drupal 8.6 it really looks like the issue is unresolved. I'm also opening a documentation issue here https://www.drupal.org/project/user_guide/issues/3047315