[bug#58587] [PATCH 00/14] Introducing pyproject-build-system.

[zimoun]

Hi Marius,

On Tue, 18 Oct 2022 at 23:51, Marius Bakke <marius@gnu.org> wrote:

> I tried to address this in the attached documentation patch.

Neat!


> The idea is to:
>
> * Recommend it for new packages in the 'guix' channel, mostly during
>   patch review.
> * Once we are confident in the implementation, remove the "experimental"
>   status and recommend it in the documentation.
> * Merge pieces of it into python-build-system as we go, such as sanity
>   check changes, using python-toolchain, etc.
> * When we "know" that there won't be any major regressions, swap out
>   python-build-system with pyproject-build-system entirely and mark the
>   latter as deprecated.

I would add a note, for instance, something like that:

diff --git a/doc/contributing.texi b/doc/contributing.texi
index 4b1eed1cb1..17dd4ec7a9 100644
--- a/doc/contributing.texi
+++ b/doc/contributing.texi
@@ -786,6 +786,24 @@ for instance, the module python-dateutil is packaged under 
the names
 starts with @code{py} (e.g.@: @code{pytz}), we keep it and prefix it as
 described above.
 
+@quotation Note
+Instead of the default Python build system @var{python-build-system}
+(@pxref{Build Systems}), we are encouraging to try the ``experimental''
+@var{pyproject-build-system} exported by @code{guix build-system
+pyproject}.  It is a reimplementation of @var{python-build-system}
+designed around @file{pyproject.toml} and
+@url{https://peps.python.org/pep-0517/, PEP 517}, and it supports a
+variety of build backends and test frameworks.
+
+It is considered ``experimental'' in that the implementation details are
+not set in stone yet.  However, there should not be any breaking
+changes, so please report any failure for new Python packages (even
+those using @file{setup.py}).
+
+Eventually this @var{pyproject-build-system} will be deprecated and
+merged back into @var{python-build-system}, probably some time in 2024.
+@end quotation
+
 @subsubsection Specifying Dependencies
 @cindex inputs, for Python packages
 


> From 628944b6f4267c4eeb5884074298b82c8d17548c Mon Sep 17 00:00:00 2001
> From: Marius Bakke <marius@gnu.org>
> Date: Tue, 18 Oct 2022 23:38:39 +0200
> Subject: [PATCH] doc: Document pyproject-build-system.
>
> * doc/guix.texi (Build Systems): Add pyproject-build-system section.
> * doc/contributing.texi (Python Modules): Mention pyproject.toml and the
> PYTHON-TOOLCHAIN package.

LGTM.

> ---
>  doc/contributing.texi | 21 +++++++++++++--------
>  doc/guix.texi         | 14 ++++++++++++++
>  2 files changed, 27 insertions(+), 8 deletions(-)
>
> diff --git a/doc/contributing.texi b/doc/contributing.texi
> index 4b1eed1cb1..b9260267fa 100644
> --- a/doc/contributing.texi
> +++ b/doc/contributing.texi

[...]

> +@defvr {Scheme Variable} pyproject-build-system
> +This is a variable exported by @code{guix build-system pyproject}.  It
> +is a reimplementation of @code{python-build-system} designed around
                             ^
s/code/var

> +@file{pyproject.toml} and @url{https://peps.python.org/pep-0517/, PEP 517},
> +and supports a variety of build backends and test frameworks.
> +
> +It is considered ``experimental'' in that the implementation details are
> +not set in stone yet, however users are encouraged to try it for new
> +Python projects (even those using @file{setup.py}) and there should not
> +be any breaking changes.
>  
> +Eventually this build system will be deprecated and merged back into
> +@code{python-build-system}, probably some time in 2024.

Idem


Cheers,
simon