More porting updates (#30635)

* Update porting_guide_2.4.rst with more docs and some rst fixes

(cherry picked from commit a0304720924e058e2bda3935352ffbe77347b77f)

1 files changed, 18 insertions, 3 deletions

diff --git a/docs/docsite/rst/porting_guide_2.4.rst b/docs/docsite/rst/porting_guide_2.4.rst
index 1ce4702c67..bf90c2b374 100644
--- a/docs/docsite/rst/porting_guide_2.4.rst
+++ b/docs/docsite/rst/porting_guide_2.4.rst
@@ -97,6 +97,21 @@ Developers should start migrating from hardcoded inventory with dynamic inventor
 
 Both users and developers should look into the new plugins because they are intended to alleviate the need for many of the hacks and workarounds found in the dynamic inventory scripts.
 
+Callback plugins
+----------------
+
+Users:
+
+* Callbacks are now using the new configuration system.  Users should not need to change anything as the old system still works,
+  but you might see a deprecation notice if any callbacks used are not inheriting from the built in classes. Developers need to update them as stated below.
+
+Developers:
+
+* If your callback does not inherit from ``CallbackBase`` (directly or indirectly via another callback), it will still work, but issue a deprecation notice.
+  To avoid this and ensure it works in the future change it to inherit from ``callbackBase`` so it has the new options handling methods and properties.
+  You can also implement the new options handling methods and properties but that won't automatically inherit changes added in the future.  You can look at ``CallbackBase`` itself and/or ``AnsiblePlugin`` for details.
+* Any callbacks inheriting from other callbacks might need to also be updated to contain the same documented options
+  as the parent or the options won't be available.  This is noted in the developer guide.
 
 Networking
 ==========
@@ -121,9 +136,9 @@ Configuration
 
 The configuration system has had some major changes. Users should be unaffected except for the following:
 
- * All relative paths defined are relative to the `ansible.cfg` file itself. Previously they varied by setting. The new behavior should be more predictable.
- * A new macro ``{{CWD}}`` is available for paths, which will make paths relative to the 'current working directory',
-   this is unsafe but some users really want to rely on this behaviour.
+* All relative paths defined are relative to the `ansible.cfg` file itself. Previously they varied by setting. The new behavior should be more predictable.
+* A new macro ``{{CWD}}`` is available for paths, which will make paths relative to the 'current working directory',
+  this is unsafe but some users really want to rely on this behaviour.
 
 Developers that were working directly with the previous API should revisit their usage as some methods (for example, ``get_config``) were  kept for backwards compatibility but will warn users that the function has been deprecated.