DOC: Discourage

Author: larsoner

source/specifications/recording-installed-packages.rst

@@ -175,14 +175,15 @@ attempt to uninstall or upgrade the package.
 (This restriction does not apply to tools that rely on other sources of information,
 such as system package managers in Linux distros.)
 
-.. warning::
-
-   If your package dynamically generates files at runtime, you will need to update
-   the ``RECORD`` file to reflect the new files. If you do not, the files will be
-   retained during uninstallation (e.g., by ``pip uninstall my_package``) likely leading
-   to issues such as the package remaining importable but errantly appearing as a
-   namespace package. See :gh:`pypa/pip/issues/11835` for discussion.
+.. note::
 
+   It is *strongly discouraged* for an installed package to modify itself
+   (e.g., store cache files under its namespace in ``site-packages``).
+   Changes inside ``site-packages`` should be left to specialized installer
+   tools such as pip. If a package is nevertheless modified in this way,
+   then the ``RECORD`` must be updated, otherwise uninstalling the package
+   will leave unlisted files in place (possibly resulting in a zombie
+   namespace package).
 
 The INSTALLER file
 ==================