From e2cd5b54a8a6dc6d59e52045879be6a6abc2e48a Mon Sep 17 00:00:00 2001 From: Jennifer Hodgdon Date: Tue, 2 Oct 2012 06:28:08 -0700 Subject: [PATCH] Issue #1539940 by jwilson3, infiniteluke, mrf, ryanissamson: Fix up README files to encourage good placement of themes, modules, and profiles --- README.txt | 30 ++++++++++++++++++++++++++++++ modules/README.txt | 20 +++++++++++++++++--- profiles/README.txt | 20 +++++++++++++++++--- sites/README.txt | 10 ++++++++++ themes/README.txt | 18 +++++++++++++++--- 5 files changed, 89 insertions(+), 9 deletions(-) create mode 100644 sites/README.txt diff --git a/README.txt b/README.txt index 5e49ac4898b..77a1d6585c4 100644 --- a/README.txt +++ b/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 ---------- diff --git a/modules/README.txt b/modules/README.txt index f4e35b55835..339aa00a6c1 100644 --- a/modules/README.txt +++ b/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 -which are common to all sites. This will allow you to more easily -update Drupal core files. +It is safe to organize modules into subdirectories, such as "contrib" for +contributed modules, and "custom" for custom modules. Note that if you move a +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. diff --git a/profiles/README.txt b/profiles/README.txt index 2bbf4c97bcb..69bb4923119 100644 --- a/profiles/README.txt +++ b/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 -which are common to all sites. This will allow you to more easily -update Drupal core files. +In multisite configuration, installation profiles found in this directory are +available to all sites during their initial site installation. Shared common +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. diff --git a/sites/README.txt b/sites/README.txt new file mode 100644 index 00000000000..0372902f15f --- /dev/null +++ b/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. diff --git a/themes/README.txt b/themes/README.txt index e9425214b2f..320b9671274 100644 --- a/themes/README.txt +++ b/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 -which are common to all sites. This will allow you to more easily -update Drupal core files. +It is safe to organize themes into subdirectories and is recommended to use +Drupal's sub-theme functionality to ensure easy maintenance and upgrades. + +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.