On 07/01/2013 04:20 PM, Stephen Gallagher wrote:
On 07/01/2013 10:05 AM, Jan Safranek wrote:
> Hi,
> we're reaching a point where we should report a version of the API
> in MOF file.
> Version is 3-component, i.e. X.Y.Z.
> No API changes are allowed during .Z releases, i.e. you may add
> new functions, add parameters to functions, add properties, add
> classes, but existing application must run without problems.
Are all parameters optional in CIM? If not, then that would be an ABI
break.
Yes, all parameters are optional.
> When Y is changed, API can be changed (property/function
> renamed/deleted etc.). Still, you do not _need_ to change the API
> if the release is a major step forward without any API breakers.
> The version should be bumped in MOF files only if appropriate class
> is changed. I.e. when you release X.Y.Z+1 version, you do not need
> to change all MOF files, change the Version qualifier only in the
> changed classes.
> Is there any volunteer to write simple API checker, which would
> compare two set of MOF files and report changes?
I don't really see where the X version comes in, honestly.
I'd like to propose an alternate approach (something slightly closer
to how C libraries are versioned).
We'll stick with three component: X.Y.Z
1) Versions are only updated at *release* time.
2) If any changes have been made to the implementation that *do not*
affect the public API at all, increment Z
3) If any changes are made that modify the public API but do not
affect backwards-compatibility (i.e. only new functions or new
optional arguments), increment Y and set Z to zero.
4) If any changes are made that modify the public API in a
non-backwards-compatible manner (a function is removed or its
mandatory arguments are changed), increment X and set Y and Z to zero.
This should make it clear to any client that needs to know
* Am I compatible with it without code changes? (X)
* Does this version support all of the functions I use? (Y)
* Has this version fixed a bug I'm working around? (Z)
I am afraid the X number could explode pretty quickly. I would reserve X
to huge concept changes. Or, we could state that Experimental classes
(=now everything in Storage) can change API also in Y release and remove
the Experimental qualifier only when it's really used and stable.
Jan