Deprecate the provisional -w flag for %pyproject_buildrequires

The option was provisional, so it had no compatibility guarantees.
We keep the option anyway: there will be no removals just for the sake of removals.

All remaining usages in Fedora Rawhide have open Pull Requests to replace it with -p,
or remove it entirely.

Examples:

 https://src.fedoraproject.org/rpms/python-scikit-misc/pull-request/13
 https://src.fedoraproject.org/rpms/python-traitlets/pull-request/8
 https://src.fedoraproject.org/rpms/packit/pull-request/1402

README.md

@@ -80,7 +80,7 @@ using the `-R` flag:
     %pyproject_buildrequires -R
 
 Alternatively, if the project specifies its dependencies in the pyproject.toml
-`[project]` table (as defined in [PEP 621](https://www.python.org/dev/peps/pep-0621/)),
+`[project]` table (as defined in [PEP 621]),
 the runtime dependencies can be obtained by reading that metadata.
 
 This can be enabled by using the `-p` flag.
@@ -92,28 +92,6 @@ Please note that not all build backends which use pyproject.toml support the
 For example, poetry-core (at least in 1.9.0) defines package metadata in the
 custom `[tool.poetry]` table which is not supported by the `%pyproject_buildrequires` macro.
 
-Finally, the runtime dependencies can be obtained by building the wheel and reading the metadata from the built wheel.
-This can be enabled with the `-w` flag and cannot be combined with `-p`.
-Support for building wheels with `%pyproject_buildrequires -w` is **provisional** and the behavior might change.
-Please subscribe to Fedora's [python-devel list] if you use the option.
-
-    %generate_buildrequires
-    %pyproject_buildrequires -w
-
-When this is used, the wheel is going to be built at least twice,
-becasue the `%generate_buildrequires` section runs repeatedly.
-To avoid accidentally reusing a wheel leaking from a previous (different) build,
-it cannot be reused between `%generate_buildrequires` rounds.
-Contrarily to that, rebuilding the wheel again in the `%build` section is redundant
-and the packager can omit the `%build` section entirely
-to reuse the wheel built from the last round of `%generate_buildrequires`.
-Be extra careful when attempting to modify the sources after `%pyproject_buildrequires`,
-e.g. when running extra commands in the `%build` section:
-
-    %build
-    cython src/wrong.pyx  # this is too late with %%pyproject_buildrequires -w
-    %pyproject_wheel
-
 For projects that specify test requirements using an [`extra`
 provide](https://packaging.python.org/specifications/core-metadata/#provides-extra-multiple-use),
 these can be added using the `-x` flag.
@@ -167,7 +145,7 @@ in worst case, patch/sed the requirement out from the tox configuration.
 Note that neither `-x` or `-t` can be used with `-R` or `-N`,
 because runtime dependencies are always required for testing.
 You can only use those options if the build backend  supports the [prepare-metadata-for-build-wheel hook],
-or together with `-p` or `-w`.
+or together with `-p`.
 However, using `-g` with `-R` or `-N` is supported because dependency groups don't need to be used for testing
 and can be obtained by reading `pyproject.toml` only.
 
@@ -184,7 +162,7 @@ Dependencies will be loaded from them:
 For packages not using build system you can use `-N` to entirely skip automatical
 generation of requirements and install requirements only from manually specified files.
 `-N` option implies `-R` and cannot be used in combination with other options mentioned above
-(`-w`, `-e`, `-t`, `-x`, `-p`).
+(`-e`, `-t`, `-x`, `-p`).
 
 The `%pyproject_buildrequires` macro also accepts the `-r` flag for backward compatibility;
 it means "include runtime dependencies" which has been the default since version 0-53.
@@ -532,6 +510,7 @@ so be prepared for problems.
 [PEP 508]: https://www.python.org/dev/peps/pep-0508/
 [PEP 517]: https://www.python.org/dev/peps/pep-0517/
 [PEP 518]: https://www.python.org/dev/peps/pep-0518/
+[PEP 621]: https://www.python.org/dev/peps/pep-0621/
 [PEP 639]: https://www.python.org/dev/peps/pep-0639/
 [PEP 735]: https://www.python.org/dev/peps/pep-0735/
 [pip's documentation]: https://pip.pypa.io/en/stable/cli/pip_install/#vcs-support
@@ -542,6 +521,11 @@ Deprecated
 
 The `%{pyproject_build_lib}` macro is deprecated, don't use it.
 
+The `%pyproject_buildrequires` `-w` option is deprecated, don't use it.
+If the build backend does not support the [prepare-metadata-for-build-wheel hook],
+consider using the `-p` flag to read the metadata from the pyproject.toml
+`[project]` table (as defined in [PEP 621]) instead.
+
 
 Testing the macros
 ------------------

macros.pyproject

@@ -192,6 +192,10 @@ fi
 fi}
 }
 %{-w:
+%{!?__pyproject_buildrequires_w_warned:%{warn:The %%pyproject_buildrequires -w option is deprecated.
+It's not efficient to build the wheel several times during the build.
+The option is not scheduled for removal, but packagers should use the -p option instead.
+}%global __pyproject_buildrequires_w_warned 1}
 %{-p:%{error:The -w and -p options are mutually exclusive}}
 }
 %{-e:%{expand:%global toxenv %(%{__python3} -s %{_rpmconfigdir}/redhat/pyproject_construct_toxenv.py %{?**})}}

pyproject-rpm-macros.spec

@@ -14,7 +14,7 @@ License:        MIT
 #   Increment Y and reset Z when new macros or features are added
 #   Increment Z when this is a bugfix or a cosmetic change
 # Dropping support for EOL Fedoras is *not* considered a breaking change
-Version:        1.16.3
+Version:        1.16.4
 Release:        1%{?dist}
 
 # Macro files
@@ -167,6 +167,9 @@ export HOSTNAME="rpmbuild"  # to speedup tox in network-less mock, see rhbz#1856
 
 
 %changelog
+* Tue Dec 03 2024 Miro Hrončok <mhroncok@redhat.com> - 1.16.4-1
+- Deprecate the provisional -w flag for %%pyproject_buildrequires
+
 * Tue Dec 03 2024 Miro Hrončok <mhroncok@redhat.com> - 1.16.3-1
 - Accept arbitrary options from %%pyproject_buildrequires in pyproject-srpm-macros
 - This will make future additions smoother

pyproject_buildrequires.py

@@ -322,9 +322,8 @@ def generate_run_requirements_hook(backend, requirements):
             'The build backend cannot provide build metadata '
             '(incl. runtime requirements) before build. '
             'If the dependencies are specified in the pyproject.toml [project] '
-            'table, you can use the -p flag to read them.'
-            'Alternatively, use the provisional -w flag to build the wheel and parse the metadata from it, '
-            'or use the -R flag not to generate runtime dependencies.'
+            'table, you can use the -p flag to read them. '
+            'Alternatively, use the -R flag not to generate runtime dependencies.'
         )
     dir_basename = prepare_metadata('.', config_settings=requirements.config_settings)
     with open(dir_basename + '/METADATA') as metadata_file:
@@ -669,7 +668,7 @@ def main(argv):
     parser.add_argument(
         '-w', '--wheel', action='store_true', default=False,
         help=('Generate run-time requirements by building the wheel '
-              '(useful for build backends without the prepare_metadata_for_build_wheel hook)'),
+              '(useful for build backends without the prepare_metadata_for_build_wheel hook, deprecated)'),
     )
     parser.add_argument(
         '-p', '--read-pyproject-dependencies', action='store_true', default=False,