[documentation] [task] Drupal core installer messages
Dries
drupal-docs at drupal.org
Wed Mar 8 19:11:20 UTC 2006
Issue status update for
http://drupal.org/node/51772
Post a follow up:
http://drupal.org/project/comments/add/51772
Project: Documentation
Version: <none>
Component: Misc
Category: tasks
Priority: critical
Assigned to: Anonymous
Reported by: webchick
Updated by: Dries
Status: active
Amazon: that feedback is invaluable! Great job.
Dries
Previous comments:
------------------------------------------------------------------------
Tue, 28 Feb 2006 17:12:58 +0000 : webchick
Attachment: http://drupal.org/files/issues/messages.txt (8.96 KB)
Attached is a list of error/status messages that the Drupal core
installer [1] generates. This list may be out of date by now; if so I
will post a follow-up that contains the new versions.
The idea is to make these error messages friendly and readable to
anyone who might be installing the software. The basic formula for good
error messages is:
1. What's the problem?
2. How do I fix the problem?
3. How do I avoid the problem in the future?
Here are some resources on writing good error messages I've come across
during my research:
* Error Message Guidelines [2]
* Error messages: More important to your website than you think [3]
* How to write Error Messages [4]
This is A LOT harder than it looks. :P But if you have experience
writing error messages, it would be awesome if you could lend a hand
here because we're pushing to get the installer finished ASAP. Remember
that this is the first impression people will have of Drupal, so we want
to make it as welcoming and friendly as possible.
Thank you very much.
[1] http://drupal.org/node/48732
[2] http://www.useit.com/alertbox/20010624.html
[3] http://www.marketingprofs.com/3/stoeckle1.asp
[4]
http://www.klariti.com/technical-writing/writing-error-messages.shtml
------------------------------------------------------------------------
Sat, 04 Mar 2006 16:35:19 +0000 : Jeremy at kerneltrap.org
Attachment: http://drupal.org/files/issues/messages_0.txt (2.43 KB)
Here is a smaller list of messages that should be focused on first.
These are from the core requirements API as defined in this patch [5].
[5] http://drupal.org/node/52289
------------------------------------------------------------------------
Sun, 05 Mar 2006 16:34:22 +0000 : webchick
Attachment: http://drupal.org/files/issues/messages_0_0.txt (5.02 KB)
OK I decided to take a stab at this, since it looks like no one else is
going to. :\ From now on, I am answering any complaints in the
forum/#drupal-support about Drupal being too hard to install with a
link to this post. :P
Here's an updated messages_0.txt, where I just overwrote the old
messages with a new one. If you can continue to break up the messages
by section of the patch like that it should make it much easier to
attack these a little bit at a time.
I wasn't able to satisfy all 3 conditions above, but I did at least try
to give a little more info about what the consequences were if something
wasn't done, and how to resolve the issues. The only problem is almost
all of the ones in messages_0.txt are really out of your hands if you
either aren't savvy with web server administration tasks, or are on
shared hosting. In these situations, really the only recourse is to
contact the web server admin for help, so there is a lot of redundancy.
:\
I wasn't sure at all what to do about the following:
- Unexpected error: function "%function" does not exist.
- Unexpected error: unable to find file "%file", function "%function"
does not exist.
And on the permissions-related ones, I've added a new variable which
would need to be populated: %path. This way people could just
copy/paste the lines into their shell.
PLEASE REVIEW. These might not be totally correct/accurate, and I think
they still read way too 'technical' for most people. I'll see what I can
do about that, but this is one area where I think we really need a
"newbie's touch."
------------------------------------------------------------------------
Mon, 06 Mar 2006 16:19:17 +0000 : Jeremy at kerneltrap.org
Thanks! I've merged your improved help texts into the latest patch
[6].
[6] http://drupal.org/node/52289
------------------------------------------------------------------------
Mon, 06 Mar 2006 16:48:38 +0000 : markus_petrux
As per webchick's suggestion, I'm posting here my comment about
safe_mode, made here [7].
Here we go...
Regarding the comment about safe_mode... while, it may make things
easier to avoid conflicts with file uploads et al, there are security
issues involved. Changing safe_mode may not be an option as it cannot
be changed in .htaccess files.
Instead of saying "it is recommended..." I would say something like
"safe_mode is enabled, consider switching it off if you have problems
with file uploads, but keep in mind safe_mode on is more secure. You
might want to contact your hosting provider.". Yeah, I know it is not
very well written, but I hope you get the idea. :-)
[7] http://drupal.org/node/52289#comment-79018
------------------------------------------------------------------------
Mon, 06 Mar 2006 16:58:34 +0000 : Morbus Iff
I thought safe_mode was the devil? /First, an anecdote. Back in July I
went to the O'Reilly Open Source Convention and gave a talk on Gallery.
While I was there, I wound up sitting at a table with Rasmus Lerdorf,
the guy who founded PHP. He's a Gallery user so while we talked about
various things, we eventually got around to talking about safe mode,
since it's one of the biggest thorns in the side of applications like
Gallery. About safe mode Rasmus says "the biggest problem with safe
mode is that people use it." And he's right. Safe mode is fundamentally
flawed because it's providing security at the application level, instead
of at the operating system level. If you can run CGI scripts (which have
no comparable safe mode) then you can do all the things that safe mode
prevents you from doing. This is like ignoring the locked door
(safe-mode PHP) and going in through the nearby open window (CGI). The
only situation where safe mode actually provides any security is in the
situation where your ISP also denies you any CGI access./
------------------------------------------------------------------------
Mon, 06 Mar 2006 17:20:01 +0000 : markus_petrux
That's a common environment for many shared hosting providers,
however...
Also, safe_mode off is a resource that has been used by PHP based
exploits in the past. That is also something to consider... even if you
can asure you're always 100% up to date, you're still open for 0 day
exploits. Of course, safe_mode on is not the only thing to take into
account, but safe_mode off is just a door that could be opened...
------------------------------------------------------------------------
Tue, 07 Mar 2006 04:53:14 +0000 : Amazon
Hi, I asked a technical person who is a non-Drupal user to review the
messages to see if they stood on their own. Here is the feedback on
the messages.
Messages from system.install:
Errors:
Drupal requires PHP version %minimum_version or greater. You are
using PHP version %installed_version. PHP must be upgraded in order
to continue. Please contact your web server administrator.
Drupal requires Apache version %minimum_version or greater. You are
using Apache version %installed_version. Apache must be upgraded in
order to continue. Please contact your web server administrator.
Drupal requires MySQL version %minimum_version or greater. You are
using MySQL version %installed_version. MySQL must be upgraded in
order to continue. Please contact your web server administrator.
Drupal requires PostgreSQL version %minimum_version or greater. You
are using PostgreSQL version %installed_version. PostgreSQL must be
upgraded in order to continue. Please contact your web server
administrator.
TechnicalNonDrupalUser: These messages are are very clear and concise.
Warnings:
PHP safe_mode is currently enabled. It is recommended that you
disable safe_mode or Drupal may have problems, for example with
handling file uploads and images. This can be done by setting the
safe_mode variable in php.ini to "0". If you do not have access to
the php.ini file, please contact your web server administrator.
TechnicalNonDrupalUser: This is out of context for me. Should you
explain how the user got in safe
mode (like Microsoft does)? If people are in CivicSpace, they may say
"hmm...what's Drupal?" I suggest rewording the second sentence to: It
is
recommended that you disable safe_mode before continuing, otherwise you
might
experience issues with things like file and image uploads.
PHP register_globals is currently enabled. As of Drupal 4.2.0 it is
advised that you disable register_globals, as it helps increase the
security of your site. This can be done by setting the
register_globals variable in php.ini to "0". If you do not have
access to the php.ini file, please contact your web server
administrator.
TechnicalNonDrupalUser: good
Your PHP installation limits Drupal to using only %current_value of
RAM. It is suggested that you modify the memory_limit directive to
allow at least %value of RAM. This can be done by setting the
memory_limit variable in php.ini to "%value". If you do not have
access to the php.ini file, please contact your web server
administrator.
TechnicalNonDrupalUser: good for an advanced user. I couldn't explain
this to my mom, but she
wouldn't be doing this stuff in the first place.
Your /settings.php/ file is currently writable by the web
server process. This is security risk, and it is advised that you
remove write permission from the file. On Unix-like systems, this can
be done with the command: chmod o-w %path/settings.php.
TechnicalNonDrupalUser: same comment as above
Apache's mod_rewrite is not enabled. You will need to enable
mod_rewrite if you wish to use Drupal's Clean URL functionality.
Please contact your web server administrator.
TechnicalNonDrupalUser: What's mod_rewrite for? Why would I use Clean
URL? What is Clean URL? How
do I enable it? This is the most abstract message so far.
For improved Drupal performance and reduced bandwidth consumption you
can enable the PHP zlib extension. If enabled, Drupal will compress
cached pages and serve these pre-compressed pages to web browsers
that support gzip, which helps speed up their browsing experience.
Please contact your web server administrator.
TechnicalNonDrupalUser: again, the tips on how to do something are more
useful
-----
Errors/warnings generated by the API:
Unexpected error: function "%function" does not exist.
TechnicalNonDrupalUser: As a techy, I understand this, but to the
average user,
"what the heck
is a function?" If I knew what this was referring to, I could suggest
some
other messages.
Unexpected error: unable to find file "%file", function "%function"
does not exist.
TechnicalNonDrupalUser: Same as above.
%type /%file/ exists but should not. This can happen if, for
example, you have created a directory that has the same name as a
file that Drupal is expecting. Please remove the %type %file.
TechnicalNonDrupalUser: Huh? How about something along the lines of
"reserved terms" or
"duplicates"?
/%file/ exists but is not a %type. This can happen if, for
example, you have created a file that has the same name as a
directory that Drupal is expecting. Please remove the %type %file.
TechnicalNonDrupalUser: Same as above? Why is this a problem? It's not
clear.
%type /%file/ does not exist.
TechnicalNonDrupalUser: assuming this is based on querying something,
this is fine.
%type /%file/ is not readable. On Unix-like systems, this can
be fixed with the command: chmod o+r %path/%file.
TechnicalNonDrupalUser: This is more about permissions and I would say
that -> "Read" permissions
are missing on %type /%file/. To enable read permissions on Unix-like
systems, ...
%type /%file/ is not writable. On Unix-like systems, this can
be fixed with the command: chmod o+w %path/%file.
TechnicalNonDrupalUser: same as above
%type /%file/ is not executable. On Unix-like systems, this
can be fixed with the command: chmod o+x %path/%file.
TechnicalNonDrupalUser: again, just say there are permissions issues ->
This file does not have
enough permissions to execute. ...etc.
%type /%file/ is readable but should not be. On Unix-like
systems, this can be fixed with the command: chmod o-r %path/%
file.
TechnicalNonDrupalUser: fine, it might be nice to say why it shouldn't
be...
%type /%file/ is writable but should not be. On Unix-like
systems, this can be fixed with the command: chmod o-w %path/%
file.
TechnicalNonDrupalUser: same as above
%type /%file/ is executable but should not be. On Unix-like
systems, this can be fixed with the command: chmod o-x %path/%
file.
TechnicalNonDrupalUser: same as above
Automatically created directory /%file/.
TechnicalNonDrupalUser: out of context
Failed to automatically create directory /%file/, insufficient
privileges. Please manually create the %file directory.
TechnicalNonDrupalUser: too vague
Automatically fixed the permissions of file /%file/.
TechnicalNonDrupalUser: hopefully, I wanted this to happen. Again, too
out of context for me to
comment.
Failed to automatically fix permissions of file /%file/,
insufficient privileges. Please manually fix these permissions, using
the commands outlined in previous messages.
TechnicalNonDrupalUser: Will the previous messages always be displayed?
If the privileges are
insufficient, how can you do it manually?
No connection to MySQL database, unable to verify MySQL version.
Please try again, double-check your spelling and ensure that you do
not have caps lock enabled. If this problem persists, check with your
hosting provider to determine the correct username, password,
hostname, and database name for your MySQL server.
TechnicalNonDrupalUser: a couple grammatical errors. Usually, the
connection has nothing
to do with
spelling. Authentication will though. If this is more of an
authenticaton error,
you should say that.
No connection to PostgreSQL database, unable to verify PostgreSQL
version. Please try again, double-check your spelling and ensure that
you do not have caps lock enabled. If this problem persists, check
with your hosting provider to determine the correct username,
password, hostname, and name for your PostgreSQL database.
TechnicalNonDrupalUser: same as above
TechnicalNonDrupalUser
More information about the documentation
mailing list