WIP: updated single_source_version with a much simpler page.

[ChrisBarker-NOAA]

Initial comment edited as of Jul 30 2024

This was quick draft I whipped out -- turns out there's interest,

As per discussion on Discourse, and #1276, here is a single source page that is far simpler, and essentially refers users to their build systems for instructions.

NOTE: There is disagreement about what should be done re versioning and a __version__ attribute. This PR is NOT the place to resolve those disagreements.

Rather, I'm hoping this page can capture the state of the practice without specification of every detail of what should be done.

I am hoping to at least capture what I think is the consensus:

The very short version:

• for a given distribution, the version string(s) should be fully consistent, and be specified in only one place.

Some detailed points:

1) When a distribution is built, it should have proper PEP-conforming version info, which is consistent within that entire distribution.

2) The user, when setting up their distribution build, should specify the version string in only one place (or only one way) - and the build system should be responsible for making sure it is consistent everywhere else (e.g. the filenames, the metadata, or attributes.

3) If a distribution maintainer wants to put an attribute in the installed importable module it should be consistent with the metadata of the installed package.

4) It's best for the community that an importable version attribute uses a consistent name: __version__ is a defacto standard for that name.

If you disagree with these points, please make that argument specifically, rather than suggesting edits that don't conform to these points. That is, let's get a consensus for what this doc should say first, and then figure out how to say it.

I think (4) is the perhaps the most controversial -- though I don't understand why. I can't see how it benefits ANYONE for different distributions to use a different name for the version string. Frankly, the only explanation I can think of for why people advocate for other names, is that that way it's harder for anyone to think that having a version string is a standard -- and they really don't want having a version string to be a standard. But I ask that if you feel that way, please make sure that the text is clear that providing a version string is OPTIONAL, rather than arguing against us using the most common name in the text.

Anyway -- my goal with this doc is to capture those points, and not be prescriptive about what should be done about having or not having a version string in the installed package.

NOTE: the preview doesn't seem to be working -- I get a 404 maybe because of the merge conflict? (which I thought I'd wait for something closer to final before worrying about)

---

📚 Documentation preview 📚: https://python-packaging-user-guide--1578.org.readthedocs.build/en/1578/

[ChrisBarker-NOAA]

By the way, when putting in links to the build system's docs, I noticed that they all support __version__, and at least flit does it by default.

So it is absolutely a common practice.

[webknjaz]

@ChrisBarker-NOAA could you try working my diagram from https://github.com/pypa/packaging.python.org/pull/1276#issuecomment-1709024176 into this?

P.S. Looks like there's a merge conflict to be solved.

[ChrisBarker-NOAA]

OK all -- I think I've addressed everyone's comments.

Also -- please see my updated initial comment -- trying to keep the scope of this very narrow.

[ChrisBarker-NOAA]

@ChrisBarker-NOAA could you try working my diagram from #1276 (comment) into this?

Hmm -- I'm trying to keep this page as simple as possible and not get into too many tech details.

But if the Doc Editors (who are they?) think it should be included, then sure.

[ChrisBarker-NOAA]

By the way, I have not idea what to do with this:

The required .readthedocs.yaml configuration file was not found at repository's root. Learn how to use this file in our configuration file tutorial.

But I suppose that explains the lack of a preview.

[webknjaz]

By the way, I have not idea what to do with this:

The required .readthedocs.yaml configuration file was not found at repository's root. Learn how to use this file in our configuration file tutorial.

But I suppose that explains the lack of a preview.

I believe RTD would build against the merge commit of your PR branch into main. Since there's merge conflicts, there's no merge commit, hence no place to check the config from.

Action item: address the merge conflicts (I personally like rebasing) and it should work then.

[ChrisBarker-NOAA]

Turns out I had not synced my fork before doing this, and it was a serious mess, due to the restructuring of the docs. So I wan't able to fix it in place.

But the discussion had gotten pretty convoluted anyway, so a new PR has its benifits:

1580