[ovirt-devel] [vdsm] new internal stable modules + proposal

[Francesco Romani]

Hi,

in the last Vdsm developer call we agreed to promote a few modules in the common repository.
The common repository provides the additional guarantees over regular modules in lib/vdsm/

- stable API
- (thus) safe to use across verticals

the planned moves are:

lib/vdsm/schedule.py -> lib/vdsm/common/schedule.py
lib/vdsm/periodic.py -> lib/vdsm/common/periodic.py
lib/vdsm/virt/api.py -> lib/vdsm/common/api.py

Question is if those modules should go under common/ or under another subdirectory, maybe infra?

Lastly, i have a proposal about better handling of those modules.

First, the mere fact a module is placed under lib/vdsm/common provides the extra guarantees I mentioned.
But should we added more annotations?

for example something like

__API__ = {}

near the top of the module

if this attribute exist, then the module is safe to use across verticals, has stable API and so forth
(this is _in addition_ to the common/ package, not as replacement).

Like:

__API__ = {
  "introduced-in": "4.14.0",
  "deprecated-from": "4.18.0",
  "removed-at": "4.20.0",
  "contact": "fromani at redhat.com"
}

We could refine further this concept if we like it. The idea is to be lightweight as possible while
carrying all the information we need.

Comments welcome as usual

bests,

-- 
Francesco Romani
RedHat Engineering Virtualization R & D
Phone: 8261328
IRC: fromani