Tutorials on Build/Install

[gianfa]

• [ x] I have searched the issues of this repo and believe that this is not a duplicate.
• [x ] I have searched the FAQ and general documentation and believe that my question is not already covered.

Feature Request

This is not really a technical feature, as much as it is more of process-related so to speak

Motivation

I use poetry a lot, both for personal projects and for academic and industrial projects (i love the dependency management engine).
However, I often encounter build problems that do not allow me to run simple projects that otherwise work with other package managers. This happens mostly when switching between minors, or sometimes even when switching between patches (breaking semver rules). See an example here: #7691.

This causes some pretty major inconsistencies, Which sometimes impact pipelines and workflows, to the point of making me reconsider using Poetry.

I often read nice explanations of why certain changes are made, in issues. I appreciate this and recognize that there must be a lot of work behind each decision, but all of this remains rather hidden from the user.

Proposal

For the above reasons I propose that a section of the documentation be dedicated to bridging the python software engineering gap for the Poetry user. The tox FAQ goes in that direction.

This could consist of tutorials and/or practical examples to deal with individual typical build/install situations.
An example of sections might be the following:

1. Little build theory: how to best use build requirements with poetry (perhaps give references to understand)
2. Use cases:

• How to deal with an old standard package, like ex no-PEP-517 (this is not very helpful, since it's too hidden and small, but it's something. other examples #3433)
• How to deal with a package that need to be built locally (see linux case)
• ...

Expected Outcome

I hope that the application of this proposal or similar, will result in significant time savings on both sides: poetry devs and poetry users; sometimes anticipating or extinguishing the possibility of error due to lack of knowledge that the average user does not have (and in my humble opinion is not due to have most of the time).

Thank you for your great work

[dimbleby]

much the best way to make docs changes happen is to contribute them.