Simplify single source

[ChrisBarker-NOAA]

I'm no longer calling this a WIP -- I hope it's close to as good as it's going to get.

This is a follow-up to #1578 -- I made a mess of it when I tried to rebase.

The goal here is to have a simple, and not opinionated, page that guides folks to their build tool of choice's way to handle version strings.

Not sure if it's a guide or a discussion -- I put in discussion, but maybe it's more of a guide.

Now that I think about it -- if it's in discussions, then maybe it could be a lot longer, and go into why one might want to (or not want to) provide a version attribute in the importable package.

But I don't know that I want to moderate THAT discussion…

---

📚 Documentation preview 📚: https://python-packaging-user-guide--1580.org.readthedocs.build/en/1580/discussions/single-source-version/

[webknjaz]

• This repository is only about distribution packages, as stated in the readme, so let’s be clear that single-sourcing versions while packaging a distribution package is the goal for this PR.

  http://packaging.python.org The "Python Packaging User Guide" (PyPUG) aims to be the authoritative resource on how to package and install distributions in Python using current tools.

  Therefore import packages that aren’t part of a distribution packages are a non-goal.

So that statement is outdated: regardless of what's stated there, we do have mentions of packaging outside of distribution packages on this site. Besides, imports coupled with distributions because they provide them.

[webknjaz]

@ChrisBarker-NOAA have you looked into the possibility of embedding a diagram? (https://github.com/pypa/packaging.python.org/pull/1276#issuecomment-1709024176) I think, it's important to demonstrate unidirectional flow of the version sourcing.

[ChrisBarker-NOAA]

OK -- I think this is in good shape, and has addressed the concerns of everyone.

Open Question: whether to include a diagram -- see: https://github.com/pypa/packaging.python.org/pull/1580#issuecomment-2286522496

Other than that -- good to go.

Editors -- anything else?

[webknjaz]

Open Question: whether to include a diagram -- see: #1580 (comment)

Thanks for acknowledging that you saw my request. What's your opinion? I don't think I saw you sharing it anywhere — have I missed it?

[bwoodsend]

What would the diagram contain? I'm guessing some flow that depicts pyproject.toml -> build backend -> project/__init__.py:__version__ -> version in package metadata? Not sure how I'd translate those into picture form short of just writing those words with rectangles round them.

[ChrisBarker-NOAA]

Open Question: whether to include a diagram -- What's your opinion?

I don't think it's necessary -- it's just not that complicated.

But I'm happy for the doc editor(s) to decide.

-CHB

[webknjaz]

@bwoodsend I made a diagram in this comment a while back: https://github.com/pypa/packaging.python.org/pull/1276#issuecomment-1709024176. I imagined it'd be reused, maybe with some modifications. It's made with Mermaid.

@ChrisBarker-NOAA okay, I hear you. In the interest of unblocking the effort, I withdraw that request for now.

[flying-sheep]

Thanks for slogging through all our comments, I think the end result is really nice and clear now!

[ChrisBarker-NOAA]

Glad it got through to the end this time!

Thanks all -- it was a slog, but it's a much better document as a result of all the input.

[bwoodsend]

Here's to never seeing FileNotFoundError: .../site-packages/xyz/version.txt ever again!