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.

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?

-----BEGIN PGP SIGNATURE----- Version: GnuPG v1.4.13 (GNU/Linux) Comment: Using GnuPG with Thunderbird - http://www.enigmail.net/ iEYEARECAAYFAlHRkB8ACgkQeiVVYja6o6M7MACgqGzdyI7wnnktoJT1zZC28SaI JOUAnA3c0ckvTrMN70SrkzWKx7GnPxMA =SoO3 -----END PGP SIGNATURE-----

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.

-----BEGIN PGP SIGNATURE----- Version: GnuPG v1.4.13 (GNU/Linux) Comment: Using GnuPG with Thunderbird - http://www.enigmail.net/ iEYEARECAAYFAlHRnNcACgkQeiVVYja6o6MClgCdHY+fCrct6T0TikneVCw4zhHY 3DwAmgLTC2yD1UUn/6+6d/8L5O0qIcGu =SdME -----END PGP SIGNATURE-----

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. 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? Jan _______________________________________________ openlmi-devel mailing list openlmi-devel(a)lists.fedorahosted.org https://lists.fedorahosted.org/mailman/listinfo/openlmi-devel

On 07/01/2013 04:36 PM, Russell Doty wrote: > Do we want to key the MOF files to a RHEL specific X.Y.Z versioning, or > have an OpenLMI version for the MOF files? If the latter, do we want to > version on a Provider by Provider basis, or have a single version for > OpenLMI? Various OpenLMI providers have different releases, e.g. -Providers was released several times while Storage was released only once in past months. I'd like to have the API versions separate.

Jan. _______________________________________________ openlmi-devel mailing list openlmi-devel(a)lists.fedorahosted.org https://lists.fedorahosted.org/mailman/listinfo/openlmi-devel

On 07/01/2013 11:13 AM, Russell Doty wrote: > On Mon, 2013-07-01 at 17:03 +0200, Jan Safranek wrote: >> On 07/01/2013 04:36 PM, Russell Doty wrote: >>> Do we want to key the MOF files to a RHEL specific X.Y.Z >>> versioning, or have an OpenLMI version for the MOF files? If >>> the latter, do we want to version on a Provider by Provider >>> basis, or have a single version for OpenLMI? > >> Various OpenLMI providers have different releases, e.g. >> -Providers was released several times while Storage was released >> only once in past months. I'd like to have the API versions >> separate. > How about having a single X version across all of OpenLMI, and let > Y and Z vary by Provider? I think you're conflating version types. What Jan is talking about here is a *functional* version that identifies the version of the API that is being served. You're talking more about a *marketing* version which is for appearances only. This is better directed at the tarball/package versioning and not the API. Please see my responses in this thread for an understanding of how an API versioning should work.

On 07/01/2013 11:13 AM, Russell Doty wrote: > On Mon, 2013-07-01 at 17:03 +0200, Jan Safranek wrote: >> On 07/01/2013 04:36 PM, Russell Doty wrote: >>> Do we want to key the MOF files to a RHEL specific X.Y.Z >>> versioning, or have an OpenLMI version for the MOF files? If >>> the latter, do we want to version on a Provider by Provider >>> basis, or have a single version for OpenLMI? >> >> Various OpenLMI providers have different releases, e.g. >> -Providers was released several times while Storage was released >> only once in past months. I'd like to have the API versions >> separate. > How about having a single X version across all of OpenLMI, and let > Y and Z vary by Provider? I think you're conflating version types. What Jan is talking about here is a *functional* version that identifies the version of the API that is being served. You're talking more about a *marketing* version which is for appearances only. This is better directed at the tarball/package versioning and not the API.

On 07/03/2013 02:45 AM, Jan Safranek wrote: > On 07/01/2013 05:17 PM, Stephen Gallagher wrote: >> On 07/01/2013 11:13 AM, Russell Doty wrote: >>> On Mon, 2013-07-01 at 17:03 +0200, Jan Safranek wrote: >>>> On 07/01/2013 04:36 PM, Russell Doty wrote: >>>>> Do we want to key the MOF files to a RHEL specific X.Y.Z >>>>> versioning, or have an OpenLMI version for the MOF files? >>>>> If the latter, do we want to version on a Provider by >>>>> Provider basis, or have a single version for OpenLMI? >>>> >>>> Various OpenLMI providers have different releases, e.g. >>>> -Providers was released several times while Storage was >>>> released only once in past months. I'd like to have the API >>>> versions separate. >>> How about having a single X version across all of OpenLMI, and >>> let Y and Z vary by Provider? >> >> I think you're conflating version types. >> >> What Jan is talking about here is a *functional* version that >> identifies the version of the API that is being served. >> >> You're talking more about a *marketing* version which is for >> appearances only. This is better directed at the tarball/package >> versioning and not the API. > > Well, I was initially thinking about having the API version and > the tarball version the same. > > Can it happen that we introduce major change internally and keep > the API version the same? I can only think of major rewrite of a > provider, e.g. from Python to C with the same CIM API, how likely > is this to happen? IMHO bumping also API version might be good idea > in this case, various corner cases and error cases might behave > differently. Sorry, when I originally commented on this, I was thinking we were versioning the classes individually, as opposed to the whole of the provider. If a whole provider is versioned independently, then it makes sense for the storage and networking provider tarball versions to match their API versions. However, it becomes less clear when dealing with the openlmi-providers package, since it contains multiple agents which should be versioned independently. We also need to talk about whole-project versioning as well. For example, we might want to talk about what shipped in Fedora 19 as being "OpenLMI 1.0 Beta". Inside that marketing version would be the

specific versions of each tarball that we ship, and inside that, the API versions provided by the agents. (For another real-world example that follows this pattern, have a look at nVidia's graphics driver versioning.) So we might have the following for Fedora 19: OpenLMI 1.0 Beta |- openlmi-providers 0.0.25 |- openlmi-account API 0.0.5 |- openlmi-fan API 0.0.6 |- openlmi-hardware 0.0.12 |- openlmi-storage 0.5.1 |- openlmi-storage API 0.5.1 And so on. Does that make sense? _______________________________________________ openlmi-devel mailing list openlmi-devel(a)lists.fedorahosted.org https://lists.fedorahosted.org/mailman/listinfo/openlmi-devel