RFC New Feature: Annotate Versions Used

[jensens]

We use a bunch of versions we can not update for several reasons.

Example: We use z3c.forms 2.3.9, but there is a bugfix release 2.3.10 out and a major release 3.3.0. We can not use the bugfix release, because it breaks tests and probably other code. Also 3.3.0 has more compatibility problems. So I'd like to stick general comment to z3c.form. This can be just text or text with a link to an issue.

I'd like to have a list of this reasons in a machine readable format in order to be read by plone.versionscheck and added to the report. Thus the input has to be plain text, so it can be displayed on command-line or added to the html report.

I do not want to introduce per-version comments, because I fear this gets difficult to keep in sync with newer releases and it is significant more work to keep the information up to date. Also this variant is simple to implement.

This can be used by buildout.coredev and also by customer projects. It helps with later updates.

I propose a simple format using the existing buildout infrastructure. A new section [versionannotations] is expected by default (may be overridden by ``versionannotations = othersectionname` in [buildout] section). The extension part of plone.versioncheck reads this section and add all annotations found there to its json output file. A single annotation can be one or more lines. like

[versionannotations]
z3c.form = 
    bugfix version 2.3.10 changes an "items" property a widget to an instancemethod. Our tests and probably other code breaks using this version.
    major versions have the same problem and other changes as well were adjustments are needed.
Products.ExternalEditor =
    major version 2.0.1 is for Zope trunk, so we should stick to 1.x for now.

On command line the output is appended at the end of the version information like so::

z3c.form
    3.2.9 ................ A versions.cfg
    3.3.0 ................ U Minor
    3.2.10 ............... U Bugfix
    bugfix version 2.3.10 changes an "items" property a widget to an instancemethod. Our tests and probably other code breaks using this version.
    major versions have the same problem and other changes as well were adjustments are needed.

Did I miss something? Other ideas?

[mauritsvanrees]

We already have versions-blacklist.cfg which can be passed to bin/checkversions (from z3c.checkversions).

I wonder if a simple comment above the version pin in versions.cfg would be enough. plone.versioncheck could display any comments that are directly above the version pin.

[jensens]

The idea of plone.versioncheck is to get all relevant information together on one comprehensive page. Currently the missing piece is, why a version is outdated - intended or because there just was a fresh release?

versions-blacklist.cfg had a different intention. Also z3c.checkversions does much less than plone.versioncheck (even if some ideas were stolen from it).

I had also the idea to use comments. Unfortunately Pythons configparser does not read comments at all. So this would need a complete custom implementation. Also we need to distinguish between common comment lines and those for plone.versioncheck, like prefixing them with # pvc: ... or alike. So thats why I keept it "buildoutish".

[jensens]

I added an experimental implementation. The source of the annotations is for now the section I proposed above. It would feel better if version pin and annotation would be closer together.

[jensens]

Probably ConfigObj solves the keep-comment problem https://pypi.python.org/pypi/configobj

[jensens]

ConfigObj is not compatible with our buildout configparser format. So I for now implemented this as proposed using a [versionannotations] section.
This is released in 1.5.0