[stable-5] Warn about using internal FQCNs for modules and actions

README.md

@@ -64,6 +64,10 @@ ansible-galaxy collection install community.general:==X.Y.Z
 
 See [Ansible Using collections](https://docs.ansible.com/ansible/latest/user_guide/collections_using.html) for more details.
 
+### FQCNs for modules and actions
+
+⚠️ The collection uses a similar directory structure for modules as the Ansible repository used for Ansible 2.9 and before. This directory structure was never exposed to the user. Due to changes in community.general 5.0.0 (using `meta/runtime.yml` redirects instead of symbolic links) some tooling started exposing the internal module names to end-users. These **internal names**, like `community.general.system.ufw` for the UFW firewall managing module, do work, but should be avoided since they are treated as an implementation detail that can change at any time, even in bugfix releases. Always use the three-component FQCN form, for example `community.general.ufw` for the UFW module. ⚠️
+
 ## Contributing to this collection
 
 The content of this collection is made by good people just like you, a community of individuals collaborating on making the world better through developing automation software.

changelogs/fragments/fqcn-warnings.yml

@@ -0,0 +1,8 @@
+deprecated_features:
+  - "Please note that some tools, like the VScode plugin (https://github.com/ansible/vscode-ansible/issues/573), or ``ansible-doc --list --type module``,
+     suggest to replace the correct FQCNs for modules and actions in community.general with internal names that have more than three components.
+     For example, ``community.general.ufw`` is suggested to be replaced by ``community.general.system.ufw``. While these longer names do work, they
+     are considered **internal names** by the collection and are subject to change and be removed at all time. They **will** be removed in
+     community.general 6.0.0 and result in deprecation messages. Avoid using these internal names, and use general three-component FQCNs
+     (``community.general.<name_of_module>``) instead
+     (https://github.com/ansible-collections/community.general/pull/5373)."