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

[Nir Soffer]

On Wed, Mar 30, 2016 at 9:20 AM, Francesco Romani <fromani at redhat.com> wrote:
> ----- 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.

Do we have deprecated internal modules?

>
> (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
> _______________________________________________
> Devel mailing list
> Devel at ovirt.org
> http://lists.ovirt.org/mailman/listinfo/devel