clarified inventory_dir changes for 2.4 (#31484)

* clarified inventory_dir changes for 2.4

added example on how to restore (mostly) old behaviour for add_hosts

fixes #30901
(cherry picked from commit dc69af50dc)

docs/docsite/rst/porting_guide_2.4.rst

@@ -24,9 +24,12 @@ Ansible will not support Python 2.4 or 2.5 on the target hosts anymore. Going fo
 Inventory
 =========
 
-Inventory has been refactored to be implemented via plugins and now allows for multiple sources. This change is mostly transparent to users. 
+Inventory has been refactored to be implemented via plugins and now allows for multiple sources. This change is mostly transparent to users.
 
-One exception is the ``inventory_dir``, which is now a host variable; previously it could only have one value so it was set globally. This means you cannot use it early in plays anymore to determine ``hosts:`` or similar keywords.
+One exception is the ``inventory_dir``, which is now a host variable; previously it could only have one value so it was set globally.
+This means you can no longer use it early in plays to determine ``hosts:`` or similar keywords.
+This also changes the behaviour of ``add_hosts`` and the implicit localhost; 
+because they no longer automatically inherit the global value, they default to ``None``. See the module documentation for more information.
 
 The ``inventory_file`` remains unchanged, as it was always host specific.
 

lib/ansible/modules/inventory/add_host.py

@@ -35,8 +35,10 @@ options:
 notes:
     - This module bypasses the play host loop and only runs once for all the hosts in the play, if you need it
       to iterate use a with\_ directive.
-    - This module is also supported for Windows targets.
+    - Windows targets are supported by this module.
     - The alias 'host' of the parameter 'name' is only available on >=2.4
+    - Since Ansible version 2.4, the ``inventory_dir`` variable is now set to ``None`` instead of the 'global inventory source',
+      because you can now have multiple sources.  An example was added that shows how to partially restore the previous behaviour.
 author:
     - "Ansible Core Team"
     - "Seth Vidal"
@@ -64,4 +66,9 @@ EXAMPLES = '''
     hostname: "{{ new_ip }}"
     ansible_host: "{{ inventory_hostname }}"
     ansible_port: "{{ new_port }}"
+
+- name: Ensure inventory vars are set to the same value as the inventory_hostname has (close to pre 2.4 behaviour)
+  add_host:
+    hostname: charlie
+    inventory_dir: "{{inventory_dir}}"
 '''