Adding docs for configuration overrides. (#690)

Author: grasmash

readme/best-practices.md

@@ -17,32 +17,11 @@ Please peruse the [examples](examples) directory for examples of various coding
 
 ## Exporting configuration
 
-All site functionality should be represented in version-controlled code. This includes all configuration. Drupal configuration is typically exported via [Features](https://www.drupal.org/project/features). 
+All site functionality should be represented in version-controlled code. This includes all configuration. Drupal configuration is typically exported via [Features](https://www.drupal.org/project/features).
 
 ### Features
 
-Features should generally follow the [KIT Feature specifications](https://www.drupal.org/project/kit).
-
-Notable principles from this specification include:
-
-- A feature should provides a collection of Drupal entities which taken together satisfy a certain use case. Example:a gallery feature provides a gallery view, a photo content type, and several blocks allowing a user to add new photos and browse those submitted by others.
-- A feature must, to the best of the creator's knowledge, use a unique code namespace.
-
-Additional guidelines include:
-
-* Each feature should be as discrete and independent as possible. Feature dependencies should be carefully considered! All dependencies should be one-way. Circular dependencies should never exist.
-
-Exceptions:
-
-* Distribution compliance guidelines are only applicable for distributions
-* Sites will often need to contain a single "sitewide" feature that defines global configuration and is required by all other features. This can be viewed as a "core" feature but should not be abused as a dumping ground for miscellany.
-
-Common mistakes:
-
-* Creation of large features that encompass many un-related components. E.g., multiple un-related content types, views, roles, permissions are all bundled into a single feature.
-* Poor design of dependencies, e.g., creation of circular dependencies.
-* Each feature has too many dependencies, so no one feature can be used in isolation, or a single feature becomes impossible to disable. E.g., the "Workflow" feature depends on the "Press Room" feature because it requires field_body which is provided by "Press Room."
-* Features are too granular. E.g., there is a separate feature for each role, a feature contains only a single view, etc.
+Please see [Configuration Management](features-workflow.md) for Features best practices.
 
 ## Configuration updates
 
@@ -55,9 +34,9 @@ Common mistakes:
 
 ## Caching
 
-Without caching, Drupal is slow. As a general rule of thumb, _try to cache everything that you can_ and _try to invalidate that cache only when it is likely to be stale_. 
+Without caching, Drupal is slow. As a general rule of thumb, _try to cache everything that you can_ and _try to invalidate that cache only when it is likely to be stale_.
 
-Caching is complex. Because caching is so complex, it's difficult to provide general guidelines for caching strategies. Here are the factors the should be considered when making caching decisions: 
+Caching is complex. Because caching is so complex, it's difficult to provide general guidelines for caching strategies. Here are the factors the should be considered when making caching decisions:
 
 * What is serving the cache? E.g., CDN, Varnish, Memcache, DB, APC, etc.
 * What is being cached? An entire page, one component of a page, bytecode, etc.

readme/features-workflow.md

@@ -134,6 +134,17 @@ Additionally, an inherent limitation of the Drupal 8 configuration system is tha
 
 Finally, you have to be careful when updating core and contributed modules. If those updates make changes to a module’s configuration schema, you must make sure to also update your exported features definitions. Otherwise, the next time you run features-import it will import a stale configuration schema and cause unexpected behavior. We need to find a better way of preventing this than manually monitoring module updates. Find more information in [this discussion](https://www.drupal.org/node/2745685).
 
+### Overriding configuration
+
+If you need to override the default configuration provided by another project (or core), the available solutions are:
+
+* Use a feature module. Features will prevent a PreExistingConfigException from being thrown when a feature containing pre-existing configuration is installed. It is recommended that you add a dependency on the features module in your feature module to ensure that features is actually enabled during installation.
+* Move your config into the a custom profile. Configuration imports for Profiles are treated differently than for module. Importing pre-existing configuration for a Profile will not throw a PreExistingConfigException.
+* Use [config rewrite](https://www.drupal.org/project/config_rewrite), which will allow you to rewrite the configuration of another module prior to installation.
+* Use the [config override system](https://www.drupal.org/docs/8/api/configuration-api/configuration-override-system) built into core. This has [some limitations](https://www.drupal.org/node/2614480#comment-10573274) of which you should be wary.
+
+Using a feature module is the recommended approach.
+
 ### Other gotchas
 
 Features is a ground-up rewrite in Drupal 8 and is maturing quickly, but may still have some traps. Developers should keep a close eye on exported features, and TA need to carefully review features in PRs for the gotchas and best practices listed above.