WIP: "modernize" single-source versioning

[ChrisBarker-NOAA]

The single-sourcing-package-version page is pretty out of date.

I've (started to) update it to reflect the current standard of practice:

I know this doc deliberately doesn't make a recommendation, but I think putting the "preferred" methods first, and noting the reasons you might not want to use the older methods will help newbies -- and I did put in a "no longer recommended" section -- up to the team to decide if we want to word it that strongly.

What I did:

• Restructured it a bit with a few sections to group related methods

• Put the declarative forms up front (setup.cfg and pyproject.toml)

• Moved setuptools-vcs from the bottom. NOTE: I'm not sure how strongly we want to recommend that at this point, I've been trying it out, and it's not all that mature -- in particular, it only works well with "standard" setups -- which might be OK for anyone starting fresh, but it's a bit clunky for those of us with legacy code structures.

• Put the methoids that use built-time and run-time version finding into "no longer recommended"

• some copy editing

This reflects my personal opinion, so will need some editing / discussion, but the page really should be modernized!

[wimglenn]

Related: https://github.com/pypa/packaging.python.org/issues/182

[flying-sheep]

We could just remove that page.

__version__ is just a convention, importlib.metadata.version('distname') is short, standardized, and always works.

Maybe we should just recommend to not bother about __version__.

[abravalheri]

We could just remove that page.

__version__ is just a convention, importlib.metadata.version('distname') is short, standardized, and always works.

Maybe we should just recommend to not bother about __version__.

Hi @flying-sheep, @wimglenn, I agree with the idea that __version__ is just a convention and that at runtime if you want to know the version of something that was installed the best is to do importlib.metadata.version('distname').

But I don't think the value of this page comes from the fact it allows you to write __version__ in your Python file... For example, even if we simply rename __version__ in the examples to _my_UGLY_private_CONST_dont_USE_it_in_runtime, the documentation page still would hold have relevant information about the build process.

Some workflows imply in using a single source of truth for the version information. Maybe because it is creating a Python wrapper for an existing library written in a compiled language. Maybe because the devs want to use the VCS as single source of truth. Maybe there are other reasons (and here I am avoiding to judge if each one of these reasons is good or not)...

But my interpretation is that the value of this page comes from it giving the user options to access version information from different files during build time, not runtime. So I don't think removing it is the best option. Maybe the content needs adjustments to reflect that reality, but I see the value in the page existing somewhere.

We can argue that there is no canonical way of doing that across multiple backends and that therefore it should be moved away from the website into another one; I understand this point of view. But I don't think the best answer is "people should not be using __version__, so let's remove the page").

[ChrisBarker-NOAA]

we rename __version__ to something less controversial

Is __version__ controversial?

Putting an attribute into the module for the version number is somewhat controversial -- but I think there's' some consensus that if you do do that, it should be called __version__.

It is certainly the most common name used.

[ChrisBarker-NOAA]

I've addressed most of the comments. As I noted in #1276, I think it's important to update this page SOON -- even if it will change again in the not-too distant future. What's published now is really, really, out of date.

[ChrisBarker-NOAA]

I think I've addressed all the comments, one way or another.There's still a bit of philosophical question about to what extent this should document the current state of the practice, vs what is hopefully the future.

I suppose that part of resolving the question is the intended audience -- is this only for people starting from scratch with a new project? Or is it also for people maintaining older projects?

And another somewhat philisophical question -- packaging has moved in the direction of robust, best practices solutions that can handle all (most) cases. But this gets away from the KISS approach -- if someone is making a small package for internal use -- it's nice to have a simple way to simply solve the problem at hand, and I'd like to see that documented.

I'm not in a position to make these judgement calls.

[sinoroc]

I like that there is a healthy discussion.

Maybe this should be merged as a large overhaul of the whole page. Then work can begin to refine specific points.

[chrysle]

Referring to https://github.com/pypa/packaging.python.org/issues/616#issuecomment-1086387067, could you probably add a more complete example about the usage of importlib.metadata?

[pradyunsg]

I've moved this to a draft status given the WIP in the title and merge conflicts, to avoid accident merges before the author or a maintainer is able to address those aspects.

[willingc]

@ChrisBarker-NOAA Let's see if we can unblock this PR since the proposed content is an improvement over what exists. Next step would be to remove the conflict and take this out of WIP. For modernizing the guides, I think we should:

• merge if significantly better than existing dated doc
• make a note in the text if there is something that still requires further discussion by maintainers
• make a note, if needed, at the top of the file explaining to the user that this has been modernized but is still under revision.

[jeanas]

@ChrisBarker-NOAA Let's see if we can unblock this PR since the proposed content is an improvement over what exists. Next step would be to remove the conflict and take this out of WIP. For modernizing the guides, I think we should:

• merge if significantly better than existing dated doc

• make a note in the text if there is something that still requires further discussion by maintainers

• make a note, if needed, at the top of the file explaining to the user that this has been modernized but is still under revision.

+1 to @willingc's comment. While the concerns expressed around, e.g., to what extent setup.cfg is obsolete, are valid, the current content of the page is very out of date, so let's try to get it updated without blocking ourselves on larger questions.

@ChrisBarker-NOAA Do you still intend to work on this PR? If not, I'd be willing to submit a redux PR (possibly more focused).

[ChrisBarker-NOAA]

Sorry I dropped the ball on this -- I"M more that happy for anyone else to pick it up -- and it's been another year, so maybe can be a bit simpler:

My advice: keep to documenting the current state of practice, and don't worry about focusing on the "best" way.

Most important is to not longer be documenting clearly out of data practices -- e.g. custom code to read the version string in a setup.py file.

[ChrisBarker-NOAA]

I've gotten a bit confused about the state of this -- there is this old PR of mine, and this one: #1276

And a recent discussion on Discourse.

I think we do have consensus that keeping old, outdated docs published is a bad idea.

That PR, concludes with:

"I've considered all the comments here but still believe removing this page is the best way forward."

My thought:

Given that this page has been around a long time, simply removing it will create dead links, etc, so I think slightly better is to replace this page with one that essentially says something along the lines of:

""" It is best practice to specify the version number of your distribution in a single place, rather than trying to keep it in sync in more than one place.

Consult your build system's docs for how best to do that. """

And maybe a set of links to the most common build systems.

But we should do something in any case.