From 535f3ec0c761dc2e8a3885e71ea9558b25476b6e Mon Sep 17 00:00:00 2001
From: Petr Bokoc <pbokoc@redhat.com>
Date: Jun 02 2020 15:01:47 +0000
Subject: Add instructions on migrating pip packages from Python 3.7 to 3.8


---

diff --git a/modules/release-notes/pages/developers/Development_Python.adoc b/modules/release-notes/pages/developers/Development_Python.adoc
index 0e4e080..a351c15 100644
--- a/modules/release-notes/pages/developers/Development_Python.adoc
+++ b/modules/release-notes/pages/developers/Development_Python.adoc
@@ -42,3 +42,99 @@ However for now, the `python3-nose` package continues to be available in the Fed
 No specific release it yet targeted to remove the `python3-nose` package.
 
 Users and packagers of dependent packages are encouraged to switch to `python3-pytest` or `python3-nose2`.
+
+== Notes on migrating user-installed pip packages
+
+When you upgrade from Fedora 30 or 31 to Fedora 32, the main Python interpreter version changes from 3.7 to 3.8.
+If you have any Python packages installed using `pip`, you must complete the following procedure to migrate them to the new version:
+
+. Install the previously main Python version:
++
+[source,bash]
+----
+sudo dnf install python3.7
+----
+
+. Get `pip` for the previously main Python version:
++
+[source,bash]
+----
+python3.7 -m ensurepip --user
+----
+
+. Observe the installed packages:
++
+[source,bash]
+----
+python3.7 -m pip list
+----
+
+. Save the list with specific versions:
++
+[source,bash]
+----
+python3.7 -m pip freeze > installed.txt
+----
+
+. Install the same packages for the now default version:
++
+[source,bash]
+----
+python3 -m pip install --user -r installed.txt
+----
+
+. Uninstall user-installed packages for 3.7; this ensures proper removal of files in `~/.local/bin`:
++
+[source,bash]
+----
+python3.7 -m pip uninstall $(python3.7 -m pip list --user | cut -d" " -f1)
+----
+
+. Optionally, clean up the now empty directory structure:
++
+[source,bash]
+----
+rm -rf ~/.local/lib/python3.7/
+----
+
+. Optionally, remove the unneeded Python version:
++
+[source,bash]
+----
+sudo dnf remove python3.7
+----
+
+Additionally, if you have any `pip` packages installed using `sudo`, run the following commands _before running the final step above which removes `python3.7`_, or install it again temporarily:
+
+. Get `pip` for the previously main Python version for `root`:
++
+[source,bash]
+----
+sudo python3.7 -m ensurepip
+----
+
+. Observe the system-installed packages:
++
+[source,bash]
+----
+sudo python3.7 -m pip list
+----
+
+. Uninstall installed packages for 3.7; this ensures proper removal of files in `/usr/local/bin`:
++
+[source,bash]
+----
+sudo python3.7 -m pip uninstall $(python3.7 -m pip list | cut -d" " -f1)
+----
+
+. Optionally, clean up now empty directory structure:
++
+[source,bash]
+----
+sudo rm -rf /usr/local/lib*/python3.7/
+----
+
+[IMPORTANT]
+====
+If you followed the first procedure, the packages are already installed for your user account, which is the preferred option. Avoid using `sudo pip` in the future; these instructions are only intended to recover users who already used `sudo pip` in the past.
+====