added note about PYTHONPATH & CYLC_PYTHONPATH

src/reference/changes.rst

@@ -38,6 +38,14 @@ Cylc 8.3.0
    :cylc-uiserver: `1.4 <https://github.com/cylc/cylc-uiserver/blob/1.4.x/CHANGES.md>`__
    :cylc-rose: `1.4 <https://github.com/cylc/cylc-rose/blob/1.4.x/CHANGES.md>`__
 
+Cylc ignores `PYTHONPATH`
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Cylc now ignores ``$PYTHONPATH`` to make it more robust to task
+environments which set this value. If you want to add to the Cylc
+environment itself, e.g. to install a Cylc extension,
+use ``$CYLC_PYTHONPATH``.
+
 
 Upgrade To The Latest Jupyter Releases
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -156,11 +164,11 @@ Combined Commands
 
 Two new commands have been added as short-cuts for common working patterns:
 
-``cylc vip`` 
+``cylc vip``
    Validate, install and plays a workflow, equivalent to:
 
    .. code-block:: bash
-   
+
       cylc validate <path>
       cylc install <path>
       cylc play <id>

src/user-guide/writing-workflows/external-triggers.rst

@@ -237,7 +237,7 @@ properties:
 - they can be located either:
 
   - in ``<workflow-dir>/lib/python/``;
-  - or anywhere in your Python library path.
+  - or anywhere in your ``$CYLC_PYTHONPATH``.
 
 - they can take arbitrary positional and keyword arguments
 - workflow and task identity, and cycle point, can be passed to trigger

src/user-guide/writing-workflows/runtime.rst

@@ -325,7 +325,7 @@ as it is running, these can be placed in:
 * ``share/bin/`` - for executables. This location is automatically added to ``PATH``
   (before the top-level ``bin/`` in the run dir).
 * ``share/lib/python/`` - for Python modules. This location is automatically added
-  to ``PYTHONPATH`` (before the top-level ``lib/python/`` in the run dir).
+  to ``$PYTHONPATH`` (before the top-level ``lib/python/`` in the run dir).
 
 .. note::