INSTALL.txt needs correction and clarification

moving to the Core queue

Thanks for reporting this.

RE #1 - In the UPGRADE.txt file, we are changing the wording so that rather than saying you need to run certain commands, it says what the objective is, like "Change file permissions, and if you're on Unix/Linux you can use this command" rather than "Run this command". We need to do that in INSTALL.txt as well.

RE #2 - I think that section is just plain wrong. On Apache, the sites/default/files directory is created, but no sites/default/private, at installation (at least with the Minimal install profile -- maybe Standard creates sites/default/private?) The INSTALL.txt shouldn't mention sites/default/private at all, in my opinion.

RE #3 - We should link to this Handbook page instead of giving the $base_url instruction -- there are many other reasons that clean URLs might not work, and this page lists several possibilities and has sub-pages that tell how to configure clean URLs on other systems:
http://drupal.org/getting-started/clean-urls

Oh. And while we're at it, the file needs to be line-wrapped at 80-characters. Currently several lines go over that width.

From INSTALL.txt:

- PHP 5.2.0 (or greater) (http://www.php.net/).

The Beta 2 release announcement says Drupal 7 requires PHP 5.2.4 now.

Looks like INSTALL.txt could use some general TLC.

I started editing this... claar has volunteered to make the next update. This is NOT DONE. I got through step #2 (and had added a step, so the numbering is not correct any more). Just attaching it here so claar can take over (THANKS!!!)

1. Finished renumbering started by jhodgdon in #5
2. Re-worded steps 2 and 3 for clarity and simplicity -- this needs the most review IMO
3. Changed Required PHP version from 5.2.0 to 5.2.4
4. Word-wrapped whole file
5. Added back in the UPPERCASE headings -- I thought they improved clarity
6. Fixed a couple misspellings "direcotry" and "functionallity"
7. Changed cron line to remove extra spaces and "www." from example.com
8. Changed all instances of "multi-site" to "multisite" for consistancy
9. In step 1, I changed "cp" back to "mv" -- mv is more likely to preserve permissions and timestamps, and I'm not sure whether cp -Rp is universal enough across various Unix/Mac systems :/

I did *not* address comment 2's point #3 (link to handbook instead of $base_url fix). Out of time for today.

I don't think we want all UPPERCASE headings for the INDIVIDUAL STEPS OF THE PROCESS. Uppercase is too much like shouting. The other changes sound good. I'll review this tomorrow (can't face it today sorry).

Subscribing.

Well, upper-casing or not, I'd vote for leaving in a concise "step title heading" if possible, rather than each step simply being a wall-of-text.

Yes, Sahin -- sorry, the general cleanup kind of sidestepped the issue a bit. I left your points #2 and #3 to jhodgdon, who is better suited to address them. Your point #1, however:

Explanations does not consider IIS for file structure and permissions (chmod o+w ...)

is addressed in comment #2 above in "RE #1" -- the current plan is to reword INSTALL.txt to use more objective-oriented language, but leave the Unix command examples in, such as:

  grant the web server write privileges to blah.php .. on a typical Unix/Linux
  command line, you would use:

    chmod o+w ...

Since including commands specific to multiple operating systems would make the instructions hard to follow, I agree with jhodgen's recommendation there. I began that work, but I believe there's more to be done.

Heine said on IRC that installation on IIS should be very similar to an Apache config, so hopefully rewording like above will be sufficient for IIS users to follow along. However, if there were a good "Configuring Drupal on IIS" or "Configuring Drupal on non-Apache web servers" document on drupal.org, I'd make a case for linking to it from INSTALL.txt.

I agree that we should not provide the steps for all possible systems - Unix/Linux is a good default. This is how it's handled in UPGRADE.txt also.

Will review more later.

I'll take a stab at updating this to a viable patch.

Here's a patch.

Regarding the original issue report:
1) Hopefully, everything that is Unix/Linux command line has been labeled as an "example command" to achieve some goal, rather than as the only way to do things.
2) The stuff about the private file directory has been removed, since this hasn't been created in the current Drupal 7 installer.
3) That separate issue will need to address what to do to fix those errors, and hopefully document them in the Handbook in an appropriate location, or better yet fix Drupal so they don't occur (or make another INSTALL.txt patch). Right now, I don't think the solution is determined? Anyway, I took that bit about $base_url out of the INSTALL.txt file and put it in the Handbook instead, since that is far from the only problem people might encounter.

I'm also upping this to major, since this file had numerous innacurracies in it, and I sincerely hope we don't ship Drupal 7's release with the file as it currently is.

Really, really nice work, jhodgdon. Several things you fixed definitely bump this to major. My review:

@@ -47,244 +51,256 @@
+   Drupal stores all information about your site in a database, so in order to
+   install Drupal, you will need to have a database, and Drupal will need
+   certain database privileges (such as the ability to create tables). There are

A bit awkward. Perhaps change to:

   Because Drupal stores all site information in a database, you must create this
   database in order to install Drupal, and grant Drupal certain database privileges
   (such as the ability to create tables).  There are

Thoughts?

@@ -47,244 +51,256 @@
+   Take note of the username, password, database name, and hostname as you
+   create the database. You will enter this information during the install.

This paragraph is gold -- nice addition.

@@ -47,244 +51,256 @@
+4. Make the sites/default directory writeable.

I like having this as its own step -- nice. "writeable" misspelled, though!

@@ -47,244 +51,256 @@
+   creating a multi-site installation, substitute the correct sites directory

multi-site -> multisite please :)

@@ -47,244 +51,256 @@
+   Drupal. After installation, the settings for the file system path may be
+   modified to store uploaded files in a different location.

This confused me at first. Perhaps change to "After installation, you may modify the file system path to store uploaded files in a different location." ?

@@ -47,244 +51,256 @@
+   a. Ensure that the new location for the path exists or create it if
+      necessary. To create a new directory named uploads, for example, use the
+      following command (from the installation directory):
+
+        mkdir uploads
+
+   b. Ensure that the new location for the path is writable by the web server
+      process. To grant write permissions for a directory named uploads, use the
+      following command (from the installation directory):

I suggest combining these into:

   a. Ensure that the new location for the path exists and is writable by the web server
      process. To create the path and grant write permissions on a Unix/Linux command
      line, use the commands:

        mkdir /path/to/uploads
        chmod a+w /path/to/uploads

Thoughts?

@@ -47,244 +51,256 @@
+8. Documentation file permissions.

Suggest "8. Revoke documentation file permissions."

@@ -47,244 +51,256 @@
+   visitors visiting pages of your site. You can configure the built-in cron

"visitors visiting" -- a bit of a funny phrase, but can't come up with better. Perhaps "those visiting" ?

@@ -47,244 +51,256 @@
+   Replace the text "http://example.com/cron.php?cron_key=RANDOMTEXT" in the

should be cron_key=YOURKEY


Powered by Dreditor.

Forgot to set status back to needs work. Setting to "bug report" due to the major inaccuracies in the old version.

Thanks! I think all the comments in #16 are on target. I'll make another patch sometime soon, unless someone beats me to it.

And by the way, that "Take note of the username..." paragraph was in the document before I edited it. I think I just moved it to its own paragraph, and perhaps reworded it. :)

OK, here's a new version addressing #16.

This looks like a great improvement. Here's a few things I noted.

1)

OPTIONAL TASKS
--------------

These aren't tasks, or at least aren't worded as tasks. They're actually module-specific requirements, but I'm not sure of a good wording for that.

2) The Blogger API, etc. are not used very often, especially when compared to the others. They should probably be last in the list.

3) The description of the modules that require outbound network connections is a bit technical and quite verbose. At the least, it should be broken into two paragraphs.

4) In step 1 of the installation process, this sentence doesn't state that it's a sample command. I don't know if that's necessary.

Move the contents of that directory into a directory within
   your web server's document root or your public HTML directory:

5) In step 3, the first sentence in the second paragraph has "site" and "all" reversed:

   Because Drupal stores site all information in a database, you must create
   this database in order to install Drupal, and grant Drupal certain database
   privileges (such as the ability to create tables). 

6) The second part of that paragraph should probably be a second paragraph, and could read as follows:

Drupal ships with the following files describing this process for your database engine: INSTALL.mysql.txt, INSTALL.pgsql.txt, and INSTALL.sqlite.txt. For further assistance, contact your web hosting provider.

I think the file names make it sufficiently clear which is for which.

7) In step 4, the following should be corrected:

(see the Multisite section of this file below).

to

(see the "Multisite Configuration" section, below).

8) In step 9, do we really want to recommend automatic cron to most Drupal users? If people have feed aggregator modules enabled, or XML sitemap, etc., it will be quite slow. I think we should still recommend setting up cron jobs as a best practice.

9) In the themes section, the following is incorrect:

a theme changes the front-end look and behavior of your site.

The word "front-end" should probably be removed, or else "or administration" be added, since some themes, like Seven, are not for front-end use.

Also, it doesn't seem precisely accurate to say that themes changes behavior, although some that include a great deal of Javascript might. I think that could be kept, though.

10) Change

It is important to install these correctly and not mix them in with the core
Drupal module and theme set (directories modules and themes at the top level).

to

Do not mix downloaded modules and themes with Drupal's core modules and themes 
(located in the top-level /modules and /themes directories).

11) The mention of multisite in the modules and themes section could be improved.

Something like:

In a multisite install, however, modules and themes can be added for use on one site only. See the "Multisite Configuration" section, below.

12) I would change

Later on you might want to write your own code, but remember to NEVER modify the
core modules and themes in Drupal modules and themes directories. Instead use
the hooks available in the Drupal API.

to

Never edit Drupal's core modules and themes. If you need to write
your own code, use the hooks available in the Drupal API. You can read more about 
the Drupal API and how to develop modules at http://drupal.org/developing/modules.
If you want to modify the look of a core theme, create a subtheme of it as described
at [link]

The current wording only mentions how to do it the right way for modules, is more verbose, and uses shouting.

13) The following sentence has an extra space:

(note that 'www.'  should be omitted if users can access your site at
http://example.com/).

14) If we are to be consistent with the changes just committed to UPGRADE.txt, then periods should be removed from all the URLs that end sentences. This needs to be done in the "More Information" section.

Good comments, thanks Evan... Here's a new patch, with more cleanup.

One note on the end-of-sentence URLs -- it only makes sense to me (and only barely!) to omit the period if the URL is at the end of a paragraph. In the middle of a paragraph, without the period it's hard to tell it's the end of a sentence.

@Sahin: Once update.txt & install.txt are updated, then we can create a task to update the documentation (create it in the "Documentation" issue queue).

@jhodgdon: I don't necessarily agree with the no-dot rule either, but it was followed in the other document. I definitely don't think it should be done in middle of paragraphs.

I'll look over this in more detail later.

RE #23 - normally, the instructions for updating and installing should not change much, during the cycle of minor releases for 7.1, 7.2, etc. The idea is that these releases are mostly for bug fixes, etc. It's just in this case that the update/install files had not been updated for a while, while Drupal 7 had been updated quite a bit (UI changes, etc.).

I think Sahin meant more that we need to make sure that the documentation in the Drupal.org handbook is up to date with these documents. I think that the way they're written in here is probably better than the online version now, because of the extensive review.

I'll open up an issue in "Drupal documentation" project when I have the time, unless you want to.

There's already an issue about updating the install guide for D7 I believe... let's see.
#538054: Review and update the Installation guide

Thanks, jhodgdon! Wow, that is an old issue now...almost 500,000 nodes ago :) I'll see if I have the time to do review on those docs after this gets committed.

Sorry to come up with more points of possible improvement:

1) I think that it might more clear to novices to call MariaDB "a fully compatible alternative to MySQL" than "a fully compatible drop-in replacement for MySQL", but that is minor.

2) As in my #2, above, could the clean URLs bullet point be moved to the top of the list, since it is the most important? (Also minor, though, and debatable.)

3) Is it true that "RSS syndication" requires the XML extension? I think actually "RSS aggregation", as in the last server requirements bullet point, would be more accurate.

4)

You may also need to consult your web hosting provider
    for instructions specific to your web host.

"consult" should be followed by "with"

5)

   So that the installation script can automatically create files and
   directories (see below), set the permissions on the sites/default directory
   so that the web server can create files and directories there.

This sentence is awkwardly worded. Is there a way to dis-entangle it? :)

6)

you can grant everyone (including
   the web server)

Should the word "user" be added, possibly, after "web server" to avoid confusion?

7) Steps 6-9 are not actually complete sentences that contain a verb. Could they be in a separate section, called something like "After You Install", and given names like the following:

1. Test your configuration.
2. Check file system settings.
3. Set up cron jobs (automated maintenance tasks).
4. (Optional) Hide documentation files from web access.

8)

At this time, you can proceed
   with the initial configuration steps suggested on the "Welcome" page.

I think this is a legacy from D6: from what I remember, the D7 starting page doesn't say "Welcome"; it just says something like "Create a new page".

9)

   - Your site runs a number of web server front-ends behind a load balancer or
     reverse proxy (modify the file system path on each server to point to a
     shared file repository).

Maybe this is just a case that has never happened for me, but I don't usually hear the word "front-ends" used in this context. I'm not sure what a better wording would be though.

10)

   When you install Drupal, its built-in cron feature is enabled, which
   automatically runs the cron tasks periodically, triggerd by people visiting
   pages of your site.

"triggerd" needs an "e".

Thanks for changing the file to recommend cron job configuration, btw! I think the built-in cron feature should really just be considered a fail-safe for people who forget or don't have the ability to do so.

11)

you can download
more at http://drupal.org/project/Modules and http://drupal.org/project/Themes

These URLs don't need capitalization. They aren't capitalized on http://drupal.org/project.

This section looks a lot better now!

12)

NOTE: for more information about multiple virtual hosts or the configuration
settings, consult the Drupal handbook at drupal.org.

Is there a specific URL to which we could point people?

SUMMARY: Most of the issues I've noted above are minor, but would be nice to get fixed. Some are debatable, too. I think one more round of review, and this can be RTBC, although it would be nice if some other people could do a review also.

One thing I noticed in re-reading the file is that it is incredibly comprehensive, which is good, but could be intimidating for people new to Drupal. A broader question is whether we should add something like a QUICKSTART.txt or README.txt with the basic version of the install instructions, so people know that it doesn't have to be a complicated process.

That might be unnecessary, though, since most of the people who are new to Drupal will probably read whatever is linked on Drupal.org, which puts the burden on us in #538054: Review and update the Installation guide to make the basic docs both simple and clear.

Thanks again, jhodgdon, for your work on this.

The language for (1) was thoroughly negotiated in another issue. Not going to revisit that now. :)

Not sure about the other points... I'll take a look. And please don't apologize for reviews. :)

Thanks, jhodgdon; no worries about the first point then - I didn't know its history. I'll probably have time to review another patch as of tomorrow.

Addressing the comments in #28 above... Took them into account (I hope) with the following exceptions and notes:

1) See comment #29.

3) You are correct. The RSS output from the node RSS feed does not use the PHP XML library.

4) I don't agree, left as-is.

6) I think on some systems (such as Windows/IIS), the web server "user" isn't ever called a "user", so it might be confusing. I think it's clear enough as it is?

8) It does say "Welcome", but it doesn't have configuration steps.

12) Added link to http://drupal.org/getting-started/6/install/multi-site -- but we need to get the /6/ out of that URL...

Note about simplifying: I can't think of any steps we could really leave out. Can you? I mean, someone can just run the install.php script and see what happens, but if they decide to read the readme files, they should get full information IMO.

Anyway, here's a new file/patch.

I've filed an issue
#959294: Add new alias
to ask for a non-6 alias to be created for that page.

In the meantime, we could also link to it in INSTALL.txt as
http://drupal.org/node/251040
I guess... probably best not to ship INSTALL.txt with a link to http://drupal.org/getting-started/6/install/multi-site ?

I think this is great, setting to RTBC. The new alias issue could be handled in a follow-up after #959294: Add new alias, or you could demote your own issue and repost with a patch that has the unaliased URL.

OPTIONAL SERVER REQUIREMENTS

Can requirements be optional? Just a thought, Maybe just "Optional Server Settings".

The file is now a bit on more verbose than necessary for my taste. Stuff like "-- the files
are in .tar.gz format and can be extracted using most compression tools" is not really necessary, I think. Still ok, though.

I was not sure if "optional requirements" made sense either, but they aren't really settings either (they are modules you need to have compiled into your PHP or Apache programs). If someone can think of another word, I'd be happy to use it.

The wording on the files is the same as what is currently in the UPGRADE.txt file, which recently went through revision.

If you have other specific suggestions for wording changes to make things more concise, please make them! We'd like the file to be as snappy as possible, without leaving out essential information.

Also, the idea is that while we give linux command line examples, we give people using other methods/OS the information they need about what is being done (i.e., we tell them what they need to accomplish, then give a linux command line example of how it could be done, rather than just saying "do this at your linux command line", since not everyone installing Drupal has access to that).

I looked at UPGRADE.txt again. It is good now. It does not contain the phrase "OPTIONAL SERVER REQUIREMENTS". I am not exactly sure to what exactly you are referring when you say the wording is the same. Probably not that important.

If "Server Settings" is not good, then maybe

• Optional Server Configuration or
• Server Configuration Tips
• Optional Taks (used in Drupal 6 INSTALL.txt)

I am not sure that the section on possible installation problems helps more than it distracts. Adds a lot of text that is only necessary if you don't follow the instructions. More specifically, I refer to this section.

The install script may also tell you that it cannot proceed until you fix
certain issues with server requirements and files. The most common file
system issues are with write permissions on directories and files:

a. Missing settings.php file.

Drupal will try to automatically create a settings.php configuration file,
which is normally in the directory sites/default (to avoid problems when
upgrading, Drupal is not packaged with this file). If auto-creation fails,
and you followed step 4 above, you can create this file yourself, using
the file sites/default/default.settings.php as a template.

For example, on a Unix/Linux command line, you can make a copy of the
default.settings.php file with the command:

cp sites/default/default.settings.php sites/default/settings.php

Next, grant write privileges to the file to everyone (including the web
server) with the command:

chmod a+w sites/default/settings.php

Be sure to set the permissions back after the installation is finished!
Sample command:

chmod go-w sites/default/settings.php

b. Files directory.

The install script will attempt to create a files storage directory in the
default location at sites/default/files (the location of the files
directory may be changed after Drupal is installed). If auto-creation
fails, and you followed step 4 above, you can create this directory
yourself. You will also need to grant the web server write permission on
this directory. Sample commands from a Unix/Linux command line:

mkdir sites/default/files
chmod a+w sites/default/files

c. Write permissions after install.

The install script will attempt to write-protect the settings.php file and
the sites/default directory after saving your configuration. If this
fails, you will be notified, and you can do it manually. Sample commands
from a Unix/Linux command line:

chmod go-w sites/default/settings.php
chmod go-w sites/default

I do like this section, but it not always necessary, so wouldn't it be better to put it in the handbook and link to it from the INSTALL.txt. I checked with Drupal 6 INSTALL.txt and it doesn't have these "in case something goes wrong remarks". It makes it look a little bit like we expect it to go wrong.

I quess "- You want to restrict access to uploaded files." needs some explanantion. (It is new comparative D6 INSTALL.txt.)

I am not quite through with reading the new INSTALL.txt carefully again, but that's all the time I have this morning. Sorry.

marked http://drupal.org/node/683892 as duplicate of this one, athough the other one is older.

@mokko: If you see up above, we changed it from "Optional Tasks", since they are clearly not tasks. I said that the most accurate phrase would be "Module-Specific Requirements" or "Server Requirements for Specific Modules", but neither of those exactly rolls off the tongue. I think it's fine to leave as is.

I see what you are saying about the troubleshooting section, but I think most people don't actually read the INSTALL.txt unless they are having problems. As such, it's probably good for it to be comprehensive.

@jhodgdon: Are there any parts of your patch from the earlier issue #683892: Text clean-up of INSTALL.txt that didn't make it in here?

Ah, I'd forgotten about that other issue. I think it's all in here...

the rest is good. A bit on the verbose side, but good.

Just a note... after this (hopefully) gets committed, we should revisit this old issue I just found deep in the depths of the issue queue:
#285053: Improve INSTALL.txt description of multi-site installation with subdirectories

Committed to CVS HEAD. Thanks.