Moving users away using pep517 as a CLI tool

[pradyunsg]

This is the issue for tracking our plans for nudging users to transition away from using pep517 from the CLI. These changes would go into the inc-pep517.build branch and not the default branch.

• Revert Pull out high-level interfaces as an extended example #83 (see Revert "Pull out high-level interfaces as an extended example" #96)
• Point to python-build in the README
• {maybe} Point to python-build from issue templates
• Add a deprecation warning when pep517.build is used
• Add a deprecation warning when pep517.checkis used
• Release a version with the warning - possibly after a bit of a wait, to give people a chance to start moving to python-build and flush out any bugs there.

Originally posted by @takluyver in #83 (comment) and edited by @pradyunsg

[matthewfeickert]

Add a deprecation warning when pep517.check is used

Apologies in advance is this is covered in an Issue already and I've failed to find it, or if this should be directed to the python-build Issues and not here (more than happy to delete this and move it to the appropriate spot), but as it isn't mentioned in PR #83, are there plans to also make an equivalent of pep517.check available in the build CLI API? Moved to https://github.com/FFY00/python-build/issues/105 given @webknjaz's suggestion (thanks!).

[webknjaz]

@matthewfeickert I think this question should belong to the python-build tracker. pep517 is going to get rid of the CLI at some point as it wasn't meant to be an official public API. OTOH since python-build is a wrapper around pep517, it's probably reasonable to have check there too.

[pganssle]

@pradyunsg What is the goal with this old vs. new branch thing? Do you have any idea what the deprecation period is going to be? I was a little surprised that y'all decided to branch instead of revert.

I will also note that I personally think that while it's a good idea to start incrementally moving people to python-build, the current release version is 0.0.4. It needs a lot of love to get to be really stable — note that it accidentally doesn't work with flit or any other non-setuptools projects, and there's a good chance we'll have to change the console script entry point.

I definitely think it should be in the PyPA namespace, but it would be very nice if we could do a much more gradual migration. I'm not even confident that a deprecation warning would be appropriate at this point because while I encourage people to be early adopters, there's a good chance it will leave a bad taste in users' mouths if we start pushing them towards python-build and it ends up causing a lot of pain (whereas I would hope that if we try to get some slightly wider natural adoption first, we can work out a lot of the kinks and for most people it will be a trivial change to the actual build script with no observable effect).

[pganssle]

I'll note that I do think it's fair to stop improving pep517.build, so changes to the issue template or the documentation saying something to the effect of, "We've frozen pep517.build for now, all improvements will go to python-build; this interface will be deprecated once python-build is stable enough."

[takluyver]

The branch was my idea. I'm OK with reverting the change on master if people prefer.

[pganssle]

The branch was my idea. I'm OK with reverting the change on master if people prefer.

To clarify my position a bit, I don't really care what branching and maintenance strategy you use, it just seems that maintaining a branch with a deprecation warning in it tends to indicate that the timeline would be pretty rapid — presumably you aren't going to stop cutting releases from master for an extended period of time.

I think that — to the extent that it is possible to do so — at least pep517.build should be maintained without an explicit deprecation warning in the code for a few months if not longer to give build a time to stabilize and grow organically. I think it would be preferable to keep pep517.build working (though not necessarily maintained or updated) for a year.

At the end of the day while I think it's fair to say that no support for this was ever really promised because it was considered "experimental", for better or worse no one else stepped up until now, and giving python-build a bad reputation by forcing people onto it before it's "battle hardened" in any way is probably not going to help matters.

[pradyunsg]

Okay, I'm picking this up and working on this, because sigh of course I have no self-control.