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

[Francesco Romani]

----- Original Message -----
> From: "Nir Soffer" <nsoffer at redhat.com>
> To: "Francesco Romani" <fromani at redhat.com>
> Cc: "devel" <devel at ovirt.org>
> Sent: Tuesday, March 29, 2016 6:00:56 PM
> Subject: Re: [ovirt-devel] [vdsm] new internal stable modules + proposal
[...]
> > 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"
> > }
> 
> Since this is internal api, I don't think we need this info. The
> guarantee you have when you
> use such module is that it will never break your code. If someone one
> is changing such module,
> it must change and test the code using it.
> 
> Maybe the "standard" __author__ ?

Yes, maybe just __author__ , __deprecated__  and perhaps __status__.

I think __deprecated__ would be fit for the task.

(take from e.g.
http://stackoverflow.com/questions/1523427/what-is-the-common-header-format-of-python-files
)

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