Update devdocs with more details about type hinting, especially deprecations

Author: ksunden

doc/devel/coding_guide.rst

@@ -350,6 +350,8 @@ will run on all supported platforms and versions of Python.
 
   - If *Linting* fails, you have a code style issue, which will be listed
     as annotations on the pull request's diff.
+  - If *Mypy* or *Stubtest* fails, you have inconsistency in type hints, which
+    will be listed as annotations in the diff.
   - If a GitHub Actions or AppVeyor run fails, search the log for ``FAILURES``.
     The subsequent section will contain information on the failed tests.
   - If CircleCI fails, likely you have some reStructuredText style issue in

doc/devel/contribute.rst

@@ -345,6 +345,8 @@ Introducing
    - Use ``_api.warn_deprecated()`` for general deprecation warnings
    - Use the decorator ``@_api.deprecated`` to deprecate classes, functions,
      methods, or properties
+   - Use the decorator ``@_api.deprecate_privatize_attribute`` to deprecate
+     attributes while keeping the internal private version.
    - To warn on changes of the function signature, use the decorators
      ``@_api.delete_parameter``, ``@_api.rename_parameter``, and
      ``@_api.make_keyword_only``
@@ -354,6 +356,23 @@ Introducing
 
    You can use standard rst cross references in *alternative*.
 
+3. Make appropriate changes to the type hints in the associated `.pyi` file.
+   The general guideline is to match runtime reported behavior.
+
+  - Items marked with ``@_api.deprecated`` or ``@_api.deprecate_privatize_attribute``
+    are generally kept during the expiry period, and thus no changes are needed on
+    introduction.
+  - Items decorated with ``@_api.rename_parameter`` or ``@_api.make_keyword_only``
+    report the *new* (post deprecation) signature at runtime, and thus *should* be
+    updated on introduction.
+  - Items decorated with ``@_api.delete_parameter`` should include a default value hint
+    for the deleted parameter, even if it did not previously have one (e.g.
+    ``param: <type> = ...``). Even so, the decorator changes the default value to a
+    sentinel value which should not be included in the type stub. Thus, Mypy Stubtest
+    needs to be informed of the inconsistency by placing the method into
+    ``ci/mypy-stubtest-allowlist.txt`` under a heading indicating the deprecation
+    version number.
+
 Expiring
 ~~~~~~~~
 
@@ -365,6 +384,19 @@ Expiring
    information. For the content, you can usually copy the deprecation notice
    and adapt it slightly.
 2. Change the code functionality and remove any related deprecation warnings.
+3. Make appropriate changes to the type hints in the associated `.pyi` file.
+
+  - Items marked with ``@_api.deprecated`` or ``@_api.deprecate_privatize_attribute``
+    are to be removed on expiry.
+  - Items decorated with ``@_api.rename_parameter`` or ``@_api.make_keyword_only``
+    will have been updated at introduction.
+  - Items decorated with ``@_api.delete_parameter`` will need to be updated to the
+    final signature, in the same way as the ``.py`` file signature is updated.
+    The entry in ``ci/mypy-stubtest-allowlist.txt`` should be removed.
+  - Any other entries in ``ci/mypy-stubtest-allowlist.txt`` under a versions
+    deprecations should be double checked, as only ``delete_parameter`` should normally
+    require that mechanism for deprecation. For removed items that were not in the stub
+    file, only deleting from the allowlist is required.
 
 Adding new API
 --------------
@@ -391,6 +423,7 @@ New modules and files: installation
 * If you have added new files or directories, or reorganized existing
   ones, make sure the new files are included in the match patterns in
   in *package_data* in :file:`setupext.py`.
+* New modules *may* be typed inline or using parallel stub file like existing modules.
 
 C/C++ extensions
 ----------------