From ed17b8e921ab26789c6811945197049e615e5408 Mon Sep 17 00:00:00 2001
From: Miro Hrončok <miro@hroncok.cz>
Date: Apr 26 2020 14:46:02 +0000
Subject: Document the automatic %python_provide


Fixes https://pagure.io/packaging-committee/issue/964

---

diff --git a/guidelines/modules/ROOT/examples/python-example.spec b/guidelines/modules/ROOT/examples/python-example.spec
index cad7dbc..7f5c431 100644
--- a/guidelines/modules/ROOT/examples/python-example.spec
+++ b/guidelines/modules/ROOT/examples/python-example.spec
@@ -20,7 +20,6 @@ rest of the description that provides more details.}
 %package -n python3-%{srcname}
 Summary:        %{summary}
 BuildRequires:  python3-devel
-%{?python_provide:%python_provide python3-%{srcname}}
 
 %description -n python3-%{srcname} %_description
 
diff --git a/guidelines/modules/ROOT/pages/Python.adoc b/guidelines/modules/ROOT/pages/Python.adoc
index 7e46098..c00bcb1 100644
--- a/guidelines/modules/ROOT/pages/Python.adoc
+++ b/guidelines/modules/ROOT/pages/Python.adoc
@@ -108,14 +108,30 @@ Using a fictional module named "example", the subpackage containing the Python 3
 
 === The %python_provide macro
 
-All packages that provide `+python3-%{srcname}+` (for any `+%{srcname}+`) SHOULD use the `+%python_provide+` macro with the package name, for example:
+All packages that provide `+python3-...+` (for any `+...+`) SHOULD use the `+%python_provide+` macro with the provide, for example:
 
 ----
-%{?python_provide:%python_provide python3-%{srcname}}
+Provides: python3-pkg_resources = %{version}-%{release}
+%{?python_provide:%python_provide python3-pkg_resources}
 ----
 
-In Fedora 31 and further, it adds a virtual provide of `+python-%{srcname}+` for Python 3 libraries.
+In Fedora 31 and further, it adds a virtual provide of `+python-...+` for Python 3 libraries.
 For previous releases, it used to add the virtual provide for Python 2 libraries.
+Since Fedora 33, it also adds virtual provide of `+python3X-...+` (for example `+python39-...+`).
+
+On Fedora 33 or newer it is no longer needed to use `+%python_provide+` for package names:
+
+----
+%package -n python3-%{srcname}
+Summary: %{summary}
+%{?python_provide:%python_provide python3-%{srcname}}
+----
+
+Such provides are now added automatically.
+(The only exception are meta-packages without files, for technical limitations.)
+Packagers SHOULD try to remove explicit `+%python_provide+` calls for package names,
+but MAY preserve them if they aim for compatibility with older releases.
+
 
 == Automatic Provides with a standardized name
 
@@ -182,7 +198,7 @@ The following macros are defined for you in all supported Fedora and EPEL releas
 
 |`+%{python_provide}+`
 |(Lua script)
-|Given a package name, evaluates to either `Provides: python-$name` or nothing at all depending on the Python version. See <<The %python_provide macro>> for an example.
+|See <<The %python_provide macro>> for detailed explanation.
 
 |`+%{python3_sitelib}+`
 |`+/usr/lib/python3.X/site-packages+`
@@ -345,5 +361,5 @@ The following briefly summarizes the guidelines for reviewers to go over:
 * *Must*: Python modules must not download any dependencies during the build process.
 * *Must*: When building a compat package, it must install using easy_install -m so it won't conflict with the main package.
 * *Must*: When building multiple versions (for a compat package) one of the packages must contain a default version that is usable via "import MODULE" with no prior setup.
-* *Should*: If you build a Python module you should use the `+%python_provide+` macro.
+* *Should*: Additional `+python3-...+` provides should be accompanied by a `+%python_provide+` call.
 * *Should*: A package which is used by another package via an egg interface should provide egg info.
diff --git a/guidelines/modules/ROOT/pages/Python_Appendix.adoc b/guidelines/modules/ROOT/pages/Python_Appendix.adoc
index 64a357b..5d9b56c 100644
--- a/guidelines/modules/ROOT/pages/Python_Appendix.adoc
+++ b/guidelines/modules/ROOT/pages/Python_Appendix.adoc
@@ -59,7 +59,6 @@ A python module which provides a convenient example.}
 %package -n python2-%{srcname}
 Summary:        %{summary}
 BuildRequires:  python2-devel
-%{?python_provide:%python_provide python2-%{srcname}}
 
 %description -n python2-%{srcname} %_description
 
@@ -67,7 +66,6 @@ BuildRequires:  python2-devel
 %package -n python3-%{srcname}
 Summary:        %{summary}
 BuildRequires:  python3-devel
-%{?python_provide:%python_provide python3-%{srcname}}
 
 %description -n python3-%{srcname} %_description
 
@@ -217,7 +215,6 @@ A python module which provides a convenient example.}
 %package -n python2-%{srcname}
 Summary:        %{summary}
 BuildRequires:  python2-devel
-%{?python_provide:%python_provide python2-%{srcname}}
 
 %description -n python2-%{srcname} %_description
 %endif
@@ -226,7 +223,6 @@ BuildRequires:  python2-devel
 %package -n python3-%{srcname}
 Summary:        %{summary}
 BuildRequires:  python3-devel
-%{?python_provide:%python_provide python3-%{srcname}}
 
 %description -n python3-%{srcname} %_description