Enhanced example

[thomassajot]

Hi,
It would be great for new user to have an idea of how a "monorepo" is setup using Pants.
In addition, it would be good to have an example where the tests are not alongside the source code, as this is a common practice in usual python code bases.

[thomassajot]

It would also include the example 3rdparty directory and other structures mentioned in the documentation.

[Eric-Arellano]

Thanks for the suggestion! We went with the top-level structure here to show off how to use Pants in the simplest case. I agree it would be helpful to show the other layouts at https://www.pantsbuild.org/docs/source-roots#examples

At the same time, we want to keep the simple example as simple as we can: #85

Any suggestions for how we could best demo two layouts without getting too confusing? I'm thinking we could have two top-level folders simple_layout, polyglot_layout. Nothing else in the top-level other than the README.md. Then, each of those two directories have their own pants.toml etc? That is, they are entirely self-contained.

[thomassajot]

Either that or create multiple example-python repos. example-python-minimal, example-python-monorepo, example-python-polyglot, ...

[kaos]

Or, multiple branches.. to keep things together...
Could name the branches according to style.. or something along those lines, perhaps.

[Eric-Arellano]

Or, multiple branches.. to keep things together...

A challenge here is maintenance. For example, we have 2.9 vs 2.8 branches already. I wouldn't want to have 2.9-minimal, 2.9-polyglot, and then have to do a distinct PR for each.

I think my bias would be still keep a single repo, but have different layouts as distinct folders. That's easier for us to maintain than multiple repos, e.g. fewer PRs to update; and it's less fragmentation -> better discovery.

[thomassajot]

This seems like a good way to go.

[Eric-Arellano]

@thomassajot any interest in getting this started? Per #85, we'd want to keep the new polyglot setup pretty simple; could even use the same code as the current example.

[sluthra1]

Do you have any new examples or good resources on understanding python sources vs distribution vs library? I think I’m missing something probably very obvious in these examples. Also for python sources what is the use of name=lib? Is this some convention or should the name change across different folders and python sources declarations ?

[benjyw]

The best resources are the docs at pantsbuild.org - and you can ask questions on our Slack channel (linked from the docs).