Working from trunk branch 'develop', gensim.__version__ reports as 3.8.1

[gojomo]

If working in a checkout/branch from develop, gensim.__version__ reports as '3.8.1, per https://github.com/RaRe-Technologies/gensim/blob/develop/gensim/__init__.py#L8

Ideally, as part of the release process, this would be updated to reflect a precise release number in release tags/packaging, but then immediately thereafter changed to indicate something non-released - perhaps based on some implied next-release number, like 3.8.4-dev or 4.0.0-dev.

[gojomo]

Using a __version__ with a hyphen-suffix, like gensim-4.0.0-dev, would be in accordance with the practice described at: https://semver.org/#spec-item-9.

But other suffixes could be used: gensim-4.0.0-develop, if we just want to literally mention the development branch, or -unreleased, -prealpha, etc.

(Potentially, even, the code setting module __version__ could detect if it's a git checkout & append commit info.)

But, anything's better than 3.8.1. Thoughts, @piskvorky @mpenkov ?

[mpenkov]

Historically, we only update the version when we make a new release.

There isn't really a reason to keep doing things that way, though. I guess the question is what to put in place of the version while the work is in progress:

• gensim-NEXTVERSION-SOMESUFFIX: where NEXTVERSION is whatever we're planning to release next, and SOMESUFFIX can be an arbitrary string. Not a huge fan of this, because we're not fortune-tellers, and we don't know what the next released version would actually be.
• gensim-PREVIOUSVERSION-unreleased: where PREVIOUS version is the most recent that version we've already released. Slightly better than the above IMHO, as it is at least accurate.
• gensim-unreleased: Slightly less inaccurate, but not particularly helpful, because it doesn't actually tell you anything about the version.
• gensim-GITHASH: may not be as helpful if the commit is local only (not part of the gensim repo)
• any others?

[gojomo]

I prefer gensim-NEXTVERSION-SOMESUFFIX, with SOMESUFFIX as either -dev or -unreleased. It'd fit the practice & implied sorting of the SemVer-2.0 conventions I linked.

Including PREVIOUSVERSION has problems, including mismatching SemVer-2.0 sorting conventions (where PREVIOUSVERSION-ANYTHING is meant to imply before plain PREVIOUSVERSION. Ideally the 1st step post-release would be to mark the development source tree to be sure further changes (& their potential bugs or behavioral changes) aren't misidentified as a frozen, named release.

I don't see occasionally mispredicting NEXTVERSION as a problem. Always assuming the source is working towards a subsequent patch/micro release is usually safe, until there's an explicit choice to roll a more-significant digit. (Strictly observing this convention might have sounded alarms before something circa-3.8.2 broke Py2.7 compatibility without the project really wanting to, yet.)

Having had the value in source be gensim-3.8.4-dev for as long as such a release was a possibility would have been fine - even if there's never such 3.8.4 a release, and it could change to gensim-4.0.0-dev at whatever moment that API/requirements changes "requiring" a major-revision land. (By my reckoning, develop is now in such a state, with its deprecation-removals and dropping of Py2.7 support.)

(Dynamically adding the GITHASH, maybe even as gensim-4.0.0-dev+GITHASH per the 'build identifier' conventions of SemVer, could make sense when an installation detects that it's inside a valid git project directory.)

[gojomo]

Just noticed a relevant PEP which doesn't allow for SemVer's exact pre-release practices but suggests a similar alternative: https://www.python.org/dev/peps/pep-0440/#id50

[piskvorky]

@mpenkov actually, how can this happen? Why would develop's setup.py contain version='3.8.1',, when we already released 3.8.3? Are the intermediate releases broken in some way?

[mpenkov]

@mpenkov actually, how can this happen? Why would develop's setup.py contain version='3.8.1',, when we already released 3.8.3? Are the intermediate releases broken in some way?

I'm late to the party, but IIRC 3.8.3 was a retrospective bugfix release. It wasn't based off develop head.

[piskvorky]

Yeah, that party was concluded by #2899 :) FYI, setup.py now says https://github.com/RaRe-Technologies/gensim/blob/b30888342e454a58ea000edc8b985a0b7ac5451b/setup.py#L355

and unless you object, let's keep the setup.py version on the "next expected release" (as opposed to our previous practice of "the latest release").

[mpenkov]

No objections :)

[piskvorky]

I now updated our release instructions to say as much, so we don't forget.