Issue #1539940 by jwilson3, infiniteluke, mrf, ryanissamson: Fix up README files to encourage good placement of themes, modules, and profiles

README.txt

@@ -4,6 +4,7 @@ CONTENTS OF THIS FILE
 
  * About Drupal
  * Configuration and features
+ * Installation profiles
  * Appearance
  * Developing for Drupal
 
@@ -42,6 +43,35 @@ More about configuration:
    http://drupal.org/project/modules
  * See also: "Developing for Drupal" for writing your own modules, below.
 
+
+INSTALLATION PROFILES
+---------------------
+
+Installation profiles define additional steps (such as enabling modules,
+defining content types, etc.) that run after the base installation provided
+by core when Drupal is first installed. There are two basic installation
+profiles provided with Drupal core.
+
+Installation profiles from the Drupal community modify the installation process
+to provide a website for a specific use case, such as a CMS for media
+publishers, a web-based project tracking tool, or a full-fledged CRM for
+non-profit organizations raising money and accepting donations. They can be
+distributed as bare installation profiles or as "distributions". Distributions
+include Drupal core, the installation profile, and all other required
+extensions, such as contributed and custom modules, themes, and third-party
+libraries. Bare installation profiles require you to download Drupal Core and
+the required extensions separately; place the downloaded profile in the
+/profiles directory before you start the installation process.
+
+More about installation profiles and distributions:
+* Read about the difference between installation profiles and distributions:
+  http://drupal.org/node/1089736
+* Download contributed installation profiles and distributions:
+  http://drupal.org/project/distributions
+* Develop your own installation profile or distribution:
+  http://drupal.org/developing/distributions
+
+
 APPEARANCE
 ----------
 

modules/README.txt

@@ -1,4 +1,18 @@
+Place downloaded and custom modules that extend your site functionality beyond
+Drupal core in this directory to ensure clean separation from core modules and
+to facilitate safe, self-contained code updates. Contributed modules from the
+Drupal community may be downloaded at http://drupal.org/project/modules.
 
-This directory should be used to place downloaded and custom modules
+It is safe to organize modules into subdirectories, such as "contrib" for
-which are common to all sites. This will allow you to more easily
+contributed modules, and "custom" for custom modules. Note that if you move a
-update Drupal core files.
+module to a subdirectory after it has been enabled, you may need to clear the
+Drupal cache so that it can be found.
+
+In multisite configuration, modules found in this directory are available to
+all sites. In addition to this directory, shared common modules may also be kept
+in the sites/all/modules directory and will take precedence over modules in this
+directory. Alternatively, the sites/your_site_name/modules directory pattern may
+be used to restrict modules to a specific site instance.
+
+Refer to the "Developing for Drupal" section of the README.txt in the Drupal
+root directory for further information on extending Drupal with custom modules.

profiles/README.txt

@@ -1,4 +1,18 @@
+Place downloaded and custom installation profiles in this directory to ensure
+separation from Drupal core profiles and to facilitate safe, self-contained code
+updates.
 
-This directory should be used to place downloaded and custom profiles
+In multisite configuration, installation profiles found in this directory are
-which are common to all sites. This will allow you to more easily
+available to all sites during their initial site installation. Shared common
-update Drupal core files.
+profiles may also be kept in the sites/all/profiles directory and will take
+precedence over profiles in this directory. Alternatively, the
+sites/your_site_name/profiles directory pattern may be used to restrict a
+profile's availability to a specific site instance.
+
+Additionally, modules and themes may be placed inside subdirectories in a
+specific installation profile such as profiles/your_site_profile/modules and
+profiles/your_site_profile/themes respectively to restrict their usage to only
+sites that were installed with that specific profile.
+
+Refer to the "Installation Profiles" section of the README.txt in the Drupal
+root directory for further information.

sites/README.txt

@@ -0,0 +1,10 @@
+This directory structure contains the settings and configuration files specific
+to your site or sites and is an integral part of multisite configurations.
+
+It is now recommended to place your custom and downloaded extensions in the
+/modules, /themes, and /profiles directories located in the Drupal root. The
+sites/all/ subdirectory structure, which was recommended in previous versions
+of Drupal, is still supported.
+
+See core/INSTALL.txt for information about single-site installation or
+multisite configuration.

themes/README.txt

@@ -1,4 +1,16 @@
+Place downloaded and custom themes that modify your site's appearance in this
+directory to ensure clean separation from Drupal core and to facilitate safe,
+self-contained code updates. Contributed themes from the Drupal community may
+be downloaded at http://drupal.org/project/themes.
 
-This directory should be used to place downloaded and custom themes
+It is safe to organize themes into subdirectories and is recommended to use
-which are common to all sites. This will allow you to more easily
+Drupal's sub-theme functionality to ensure easy maintenance and upgrades.
-update Drupal core files.
+
+In multisite configuration, themes found in this directory are available to
+all sites. In addition to this directory, shared common themes may also be kept
+in the sites/all/themes directory and will take precedence over themes in this
+directory. Alternatively, the sites/your_site_name/themes directory pattern may
+be used to restrict themes to a specific site instance.
+
+Refer to the "Appearance" section of the README.txt in the Drupal root
+directory for further information on theming.