From d21c2caf1dbd69ba630075e48254131499f01afe Mon Sep 17 00:00:00 2001
From: Clark Boylan <clark.boylan@gmail.com>
Date: Mon, 8 Nov 2021 08:56:18 -0800
Subject: [PATCH] Clarify the need for setup.py with PEP517

There was a misunderstanding that PBRs PEP517 build hooks meant we no
longer needed a setup.py. But it turns out the setuptools build_meta
hooks that we wrap call out to setup.py. This means PBR will continue to
need to be used in conjunction with a setup.py.

This is better for backward compatibiltiy anyway so not a huge loss.

Document this more properly and update the test to reflect it.

Change-Id: If4320da1e89a5c765e0bfe56b724364f9cba34f3
---
 doc/source/user/using.rst   | 11 +++++++++--
 pbr/tests/test_packaging.py |  8 +++-----
 2 files changed, 12 insertions(+), 7 deletions(-)

diff --git a/doc/source/user/using.rst b/doc/source/user/using.rst
index 7070e017..21aa99be 100644
--- a/doc/source/user/using.rst
+++ b/doc/source/user/using.rst
@@ -37,8 +37,11 @@ something like this::
 ``pyproject.toml``
 ------------------
 
-As an alternative to writing a ``setup.py`` you can instead setup PBR
-through the PEP 517 build-system configuration in ``pyproject.toml``.
+PBR can be configured as a PEP517 build-system in ``pyproject.toml``. This
+currently continues to rely on setuptools which means you need the above
+``setup.py`` file to be present. The main benefits to using a
+``pyproject.toml`` file with PBR are that you can control the versions of
+PBR, setuptools, and wheel that are used avoiding easy_install invocation.
 Your build-system block in ``pyproject.toml`` will need to look something
 like this::
 
@@ -46,6 +49,10 @@ like this::
     requires = ["pbr>=5.7.0", "setuptools>=36.6.0", "wheel"]
     build-backend = "pbr.build"
 
+
+Eventually PBR may grow its own direct support for PEP517 build hooks, but
+until then it will continue to need setuptools and ``setup.py``.
+
 .. _setup_cfg:
 
 ``setup.cfg``
diff --git a/pbr/tests/test_packaging.py b/pbr/tests/test_packaging.py
index 7d55d549..a024f564 100644
--- a/pbr/tests/test_packaging.py
+++ b/pbr/tests/test_packaging.py
@@ -229,9 +229,6 @@ class CreatePackages(fixtures.Fixture):
         self.packages = packages
 
     def _writeFile(self, directory, file_name, contents):
-        if not contents:
-            # We want to be able to override not having files
-            return
         path = os.path.abspath(os.path.join(directory, file_name))
         path_dir = os.path.dirname(path)
         if not os.path.exists(path_dir):
@@ -924,6 +921,8 @@ class TestRequirementParsing(base.BaseTestCase):
 
 class TestPEP517Support(base.BaseTestCase):
     def test_pep_517_support(self):
+        # Note that the current PBR PEP517 entrypoints rely on a valid
+        # PBR setup.py existing.
         pkgs = {
             'test_pep517':
                 {
@@ -931,8 +930,7 @@ class TestPEP517Support(base.BaseTestCase):
                         sphinx
                         iso8601
                     """),
-                    # Override no setup.py.
-                    'setup.py': '',
+                    # Use default PBR test setup.py.
                     'setup.cfg': textwrap.dedent("""\
                         [metadata]
                         name = test_pep517