Change default gathering policy, add to docs.

CHANGELOG.md

@@ -7,6 +7,7 @@ Major features/changes:
 
 * The deprecated legacy variable templating system has been finally removed.  Use {{ foo }} always not $foo or ${foo}.
 * Any data file can also be JSON.  Use sparingly -- with great power comes great responsibility.  Starting file with "{" or "[" denotes JSON.
+* Added 'gathering' param for ansible.cfg to change the default gather_facts policy.
 
 New Modules:
 

docsite/rst/intro_configuration.rst

@@ -211,6 +211,16 @@ is very very conservative::
 
    forks=5
 
+.. _gathering:
+
+gathering
+=========
+
+New in 1.6, the 'gathering' setting controls the default policy of facts gathering (variables discovered about remote systems).
+
+The value 'implicit' is the default, meaning facts will be gathered per play unless 'gather_facts: False' is set in the play.  The value 'explicit' is the inverse, facts will not be gathered unless directly requested in the play.
+
+The value 'smart' means each new host that has no facts discovered will be scanned, but if the same host is addressed in multiple plays it will not be contacted again in the playbook run.  This option can be useful for those wishing to save fact gathering time.
 
 hash_behaviour
 ==============

examples/ansible.cfg

@@ -24,12 +24,13 @@ transport      = smart
 remote_port    = 22
 module_lang    = C
 
-# This setting controls implicit fact gathering, valid values are
-# implicit, explicit or smart (default).
-# smart gathers only if facts for that host are not currently in memory.
-# implicit set the default of gather_facts to True, explicit sets it
-# to False. This does NOT affect explicit 'gather_facts' entries.
-gathering = smart
+# plays will gather facts by default, which contain information about
+# the remote system.
+#
+# smart - gather by default, but don't regather if already gathered
+# implicit - gather by default, turn off with gather_facts: False
+# explicit - do not gather by default, must say gather_facts: True
+gathering = implicit
 
 # additional paths to search for roles in, colon separated
 #roles_path    = /etc/ansible/roles

lib/ansible/constants.py

@@ -134,7 +134,7 @@ DEFAULT_SU = get_config(p, DEFAULTS, 'su', 'ANSIBLE_SU', False, boolean=True)
 DEFAULT_SU_FLAGS = get_config(p, DEFAULTS, 'su_flags', 'ANSIBLE_SU_FLAGS', '')
 DEFAULT_SU_USER = get_config(p, DEFAULTS, 'su_user', 'ANSIBLE_SU_USER', 'root')
 DEFAULT_ASK_SU_PASS = get_config(p, DEFAULTS, 'ask_su_pass', 'ANSIBLE_ASK_SU_PASS', False, boolean=True)
-DEFAULT_GATHERING = get_config(p, DEFAULTS, 'gathering', 'ANSIBLE_GATHERING', 'smart').lower()
+DEFAULT_GATHERING = get_config(p, DEFAULTS, 'gathering', 'ANSIBLE_GATHERING', 'implicit').lower()
 
 DEFAULT_ACTION_PLUGIN_PATH     = get_config(p, DEFAULTS, 'action_plugins',     'ANSIBLE_ACTION_PLUGINS', '/usr/share/ansible_plugins/action_plugins')
 DEFAULT_CALLBACK_PLUGIN_PATH   = get_config(p, DEFAULTS, 'callback_plugins',   'ANSIBLE_CALLBACK_PLUGINS', '/usr/share/ansible_plugins/callback_plugins')