@njs Any thoughts on whether renaming pep440 crate to something (like python-version-parser or python-packaging-parsers) would be a thing that you (and your fellow maintainer) would be be amenable to?
1 Like
For project releases that predate a hypothetical amendment to the versioning scheme, then the amending PEP itself will necessarily explain what won’t work with older parsing libraries (presumably failing to parse whatever new spelling the accepted amendment added).
For project releases after such a PEP was accepted, using the PEP numbers in documentation would still be fine (e.g. “Supports PEP 440 version numbers, cannot parse PEP XYZ version numbers yet”)
We’re pretty unlikely to make substantial changes to the version format though - 440 already intentionally excluded some of the weirder variations, and has a compatibility section discussing how to represent other versioning schemes (mostly “translate to a .devN or .N suffix to provide an explicit relative order”).
If a change were ever to be made, it would be more likely to be along the lines of more explicit version translation support, with a separate “Version-Alias” field that was only ever checked for exact string matches.
1 Like
That makes sense, just when it comes to tools which generate, ingest
or interpolate version strings, it seems normal to want to be able
to indicate what revision(s) of a versioning standard they support.
I come from traditional projects which are explicit about, e.g.,
which specific IETF RFCs describe the protocols they implement, so
this apparent desire to hide specifications from engineers by
avoiding or removing references to them seems counterproductive. I
get that it’s probably just a matter of me being accustomed to
different engineering communities with their own idiosyncrasies, but
I personally find the specifications and their history of
revisions/replacements quite useful for understanding the tools I
rely upon.
1 Like
The PITA that is dealing with IETF RFC deprecations was a key motivator in deciding not to continue with the PEP number centric approach and switch to stable “latest” URLs instead.
The PEP numbers still exist when old versions need to be referenced explicitly, but for most use cases a stable URL that always gives the active version of the relevant spec is more convenient.
Thanks, that makes more sense. My concern was precisely that there
are going to be times when a project needs to refer to a particular
historical state of some standard, for example when you’ve
implemented support for that standard as written and can’t promise
that the present state of your project will necessarily be able to
support some hypothetical future state of that standard (e.g. if
that future state adds features that your software lacks parity
with).
To use PEP 440 as an example, say I have a version parser and it
supports all the syntax PEP 440 presently covers, but the “Python
Versioning Standard” gets extended by PEP XYZ in a few years. Having
documentation for an old release of my project say that it “Supports
the Python Versioning Standard” would be disingenuous, when what I
really mean is that it supports the contemporary state of that
standard as it existed when the release was made, and you’ll need to
upgrade if you want support for features which were later added to
the standard.
In such cases I’m perfectly happy to say that the project supports
PEP 440 (and link to the PEP) rather than only linking to the
evolving standard. It sounded like the community at large felt like
referring to PEPs from documentation was just generally a terrible
idea and should be avoided at all costs.
1 Like
I think it should not be the norm - the expectation is that projects will keep up with changes to the standards. But amending the documentation when a change to the standard comes out to say “the changes in PEP xxx have not yet been implemented” (and then removing that statement once they have!) is entirely reasonable IMO.
This assumes that documentation is not versioned and shipped with
software. In the ecosystems where I develop, the software comes with
documentation which reflects its capabilities, and revisions to the
documentation are also revisions to the software. Updating the
documentation to say “we don’t support this new thing yet” can’t be
magically inserted into what was distributed with prior versions of
the software. Sure users can be directed to consult an updated copy
of documentation which is not tied to what they installed, but that
defeats the purpose of providing versioned documentation with the
software.
I suppose the alternative is to embed a copy of the specification
with the documentation (or otherwise duplicate the information
therein) so that it can be frozen in time, and not refer to an
unversioned Python community standard. My point was there’s a reason
people version and/or date standards, and provide revision histories
for them. It’s basically a time machine problem.
IMO this is the way to go. Product docs can say “Implements standard foo as of January 2023”, and the standards should include changelogs with dates, like here.
If that sounds like a good idea, someone could add history sections to existing standards. Even single-entry changelogs would be useful, to set expectations.
Would PyPA welcome PRs for that? (Or rather, what needs to happen so someone can answer that on behalf of PyPA?)
That’ll work for the PEP for a new standard, but it’ll be less useful with PEPs that change an existing standard.
(And of course, it doesn’t work well for a project name, if you intend to update the project later.)
1 Like
Yes. Just submit PRs for the specs with the appropriate history sections. I don’t think there’s any formal “PyPA approval” needed for this, but as PEP-delegate for many of those specs, I’m going to say that I approve this approach, just for the record 
IMO, it’s pretty much implied by the comments in PyPA Specifications — PyPA documentation about including “Changes” sections in specifications, although that doesn’t explicitly ask for the change information to be dated.
2 Likes
OK, I filed Add changelogs to all standards · Issue #1203 · pypa/packaging.python.org · GitHub
Any PyPA member with time for mentoring/reviewing can (I hope) add the “good first issue” label.
3 Likes