On 01/20/2017 01:15 AM, Markus Armbruster wrote: >>> Isn't Since: 2.5 misleading? The anonymous type goes back to 2.5, but >>> the name doesn't. >> >> It matches what we've done elsewhere - when refactoring .json files to >> create a new type, but where the new type doesn't represent anything >> different over the wire than what was previously sent, we've documented >> the new struct name as of the older release where the wire format was >> introduced. But as long as the command says 'since 2.5', I'm okay if we >> want to mark the struct as 'since 2.9', if that's easier to think about. > > Sticking to established practice is better than inconsistent practice. > > That said, I wonder why we bother to track "since" for types. "Since" > is important information for external interfaces. Why is it useful for > purely internal ones? > > External visible are commands, events, and members of types used by > commands or events.
I guess what we can do is treat a type-wide 'Since: 2.5' as the default for all its members that don't supply any other '(since 2.6)' note. You're right that types themselves (even when used in a command) are NOT the API, and that we can refactor type names without breaking wire compatibility, but having a default for when each member of the type was first made available makes sense since we DO care when members were introduced. -- Eric Blake eblake redhat com +1-919-301-3266 Libvirt virtualization library http://libvirt.org
signature.asc
Description: OpenPGP digital signature
