Re: [Docutils-develop] say goodbye to __version_details__?

On Mon, Jun 19, 2017 at 4:05 PM, Guenter Milde via Docutils-develop
<doc...@li...> wrote:
> On 2017-06-15, David Goodger wrote:
>> On Thu, Jun 15, 2017 at 3:56 PM, Guenter Milde wrote:
>>> On 2017-06-14, David Goodger wrote:
>
>
>> I'd *much* prefer that we explicitly set a releaselevel value, not use
>> an implicit "empty string means in development".
>
> Agreed.
>
>> Alpha/beta/etc. are universally recognized, therefore:
>
>> +1 for releaselevel='alpha', release=False
>> -1 for releaselevel='', release=False
>> +0 for releaselevel='(something)', release=False
>
> Alpha/beta/etc. are commonly used and recognized to denote
> the `development status`__.
>
> __ https://blog.codinghorror.com/alpha-beta-and-sometimes-gamma/
>
> Therefore I have the following
>
> Suggestions
> ===========
>
> 1. releaselevel == development status
> -------------------------------------
>
> Don't use release level '(repository)' or '!repository' or ''.
> The information "repository" vs. "release" is already encoded as:
>  release = False   Suffix ".dev"
>  release = True    no developmental release segment
>
> Instead, use `releaselevel` for the development status of either
>
> * the repository (if release == False) or
> * the release    (if release == True).

+1

> Motivation: even if no release is planned, the repository has a
> development status in the sense that we can recommend it for
>
> alpha      internal testing,
> beta       external testing,
> candidate  pre-test of an upcoming release,
> final      production use and inclusion in distributions
>
> I have no clear preference whether to keep the name or call it
> ``development_status`` instead.

My clear preference is to keep the name "releaselevel", because that's
what sys.version_info calls it. Record that "releaselevel =
development status" in the docstring.

> 2. default repository status == "beta"
> --------------------------------------
>
> The "in development, no release planned" stage defaults to
>
>   releaselevel='beta', serial='0', release=False.

NB: This would prevent us from ever using the "alpha" status. I am not
strongly against this, just pointing it out.

It seems odd to start at "beta". Just as easy to make "alpha" the
default development status, and skip "beta".

But we can use "beta" for now. In future, if we find that we need an
"alpha" status, we can start using it then.

> Motivation:
>
> * "Beta" seems the best match when comparing the `description of the
>   development stages`__ with the state of the repository and our release
>   policies --- which state that the code in the repository is
>   a) *experimental* until the major version number reaches 1 and
>   b) always kept in a *stable* state (usable and as problem-free as
>      possible).
>
>   __ https://en.wikipedia.org/wiki/Software_release_life_cycle
>
> * In Docutils' ``setup.py``, we use the trove classifier ::
>
>     'Development Status :: 4 - Beta',

We can and should change this to match the actual status, on an ongoing basis.

> 3. status change == freeze/thaw
> -------------------------------
>
> A change of the "repository development status" would require prior
> announcement and "rough consensus" on the developer list:
>
>   beta->candidate == "feature freeze": No new features, only bugfixes.
>
>   candidate->final == "freeze": No commits without affirmation by the
>                                 release manager.
>
>   final->beta == "back to normal": Development according to the policies:
>                                    tested new features allowed, keep API
>                                    Bugs may still slip in due to
>                                    incomplete tests or clients depending
>                                    on internal features.

Clarification: final → version number bump + beta

> Hypothetical:
>
>   beta->alpha: In case a developer wants to add a new and experimental
>                feature (e.g. merging a feature branch) and expects
>                "toothing problems" we may agree to an "alpha period" (and
>                possibly an alpha release for interested testers).
>
>   (The move beta->alpha will "throw back" the version (0.15a < 0.15b).
>   This is OK, we don't want users *updating* from a beta version to an
>   alpha version. Alpha testers must clearly specify the desired version.)

-1: This seems wrong to me. Can you point out any project that does this?

"Alpha testers must clearly specify the desired version." Specify how?

> A typical cycle would be:
>
>    releaselevel=beta            0.15b.dev     [0.15b]¹
>    releaselevel=candidate       0.15rc1.dev    0.15rc1
>   [releaselevel=candidate       0.15rc2.dev    0.15rc2]²
>    releaseleve=final            0.15.dev       0.15
>    releaselevel=beta            0.16b.dev     [0.16b]
>
> ¹Beta releases are optional.
> ²Follow-up pre-releases as required.
>
> Bugfix releases use a branch.
>
> * If development shall continue during the freeze periods, we can also
>   set up the maintenance branch already with/for the pre-release (candidate).
>   Cherry-picking is easy with, e.g. git-svn.
>
> * To keep the repository reasonably small, older maintenance branches should
>   be deleted (moved to the attic). Version control ensures they can be
>   revived if required.
>
>
> set_version and redundancy
> ==========================
>
>>> I agree with Engelbert that the "magic" to set/update version_info and
>>> version identifier should be in a separate "set_version" script (this may
>>> be a shell script or a python script). This leaves docutils/__init__.py
>>> small, clean, and explicit.
>
>> I agree that docutils/__init__.py ought to be all those things. If
>> you're OK with duplicate/redundant version info in
>> docutils/__init__.py, and we have a "set_version" script that can set
>> these well, then sure. Until that script is updated, we'll need to
>> manually update these.
>
> I am fine with some duplication in docutils/__init__.py, especially if it
> is auto-managed in the long run. However, I wonder if we really need the
> same info at *three* places (version identifier, info, and details).

We don't *need* all three, except that it's more work and bother (and
potential incompatibility) to remove it. We've spent more time and
effort arguing over this than will be saved by any conceivable change,
over the remainder of Docutils' foreseeable lifetime.

> We can reduce the redundancy by:

Let's reduce the amount of meaningless navel gazing instead, yes?

> * using __version_info__ to document/explain the segments of the
>   __version__ identifier (major, minor, micro, ...),
>
> * "retiring" __version_details__:   Keep the variable for backwards
>   compatibility and special cases ('snapshot of r2045', say) but leave it
>   emtpy for cases that are clearly indicated by the "modern" replacements
>   __version_info__ and the PEP 440 version identifier (development,
>   pre-release, release)::
>
>     __version_details__ = ''
>     """
>     Optional extra version details (e.g. 'snapshot 2005-05-29, r3410').
>
>     For development and release status see `__version_info__`
>     and `__version__`.
>     """

+0, if it really bothers you so much.

> Alternatively (if someone insists on keeping __version_details__ alive),
> move __version_info__ to a separate module, ``docutils.version_info`` or
> ``docutils.utils.version_info``, say.
>    Clients in need of a version comparing operation would load the module
> which on import would parse the __version__ identifier and set
> docutils.version_info.version_info.

-1. KISS. This is way more effort than necessary. And **again**, the
whole point of __version_info__ is to remove any need to parse
__version__.

What we have now is fine, and what we'll have in 0.15 is better, more
than good enough. Let's stop flogging this dead horse.

David Goodger
<" rel="nofollow">http://python.net/~goodger>