Re: [PATCH v2 03/34] docs: generated: enums: libvirt: append 'Since version' metadata

On Tue, Apr 19, 2022 at 15:17:07 +0200, Victor Toso wrote: > On Tue, Apr 19, 2022 at 02:40:05PM +0200, Peter Krempa wrote: > > On Thu, Apr 14, 2022 at 22:47:14 +0200, Victor Toso wrote: > > > typedef enum { > > > VIR_DOMAIN_RUNNING_UNKNOWN = 0, > > > - VIR_DOMAIN_RUNNING_BOOTED = 1, /* normal startup from boot */ > > > - VIR_DOMAIN_RUNNING_MIGRATED = 2, /* migrated from another host */ > > > - VIR_DOMAIN_RUNNING_RESTORED = 3, /* restored from a state file */ > > > - VIR_DOMAIN_RUNNING_FROM_SNAPSHOT = 4, /* restored from snapshot */ > > > - VIR_DOMAIN_RUNNING_UNPAUSED = 5, /* returned from paused state */ > > > - VIR_DOMAIN_RUNNING_MIGRATION_CANCELED = 6, /* returned from migration */ > > > - VIR_DOMAIN_RUNNING_SAVE_CANCELED = 7, /* returned from failed save process */ > > > + VIR_DOMAIN_RUNNING_BOOTED = 1, /* normal startup from boot (Since: v1.0.0) */ > > > + VIR_DOMAIN_RUNNING_MIGRATED = 2, /* migrated from another host (Since: v1.0.0) */ > > > > Your script doesn't seem to handle well versions prior to > > v1.0.0. This specific constant was added in commit > > v0.9.1-133-gd65a924b34 thus it should be 'Since v0.9.2'. > > I actually followed the suggestion to started with v1.0.0. I can > change it to work with the exact tags that it would first appear > in libvirt if you think it is necessary. CC'ing Andrea for input. I have no problem with adding an arbitrary cut-off. It just must be clear that it's from an older version, thus 'Since: v1.0.0' must not be used in such case. > > I understand that we might not want to deal with too old > > releases, but in such case we should rather pick a different > > marker meaning that the symbol was added too long ago. > > Since v1.0.0 is not wrong if it was introduced before v1.0.0. It > is just a criteria for adding the version metadata for too old > releases, after the fact. It is not wrong but misleading in the context of other tags where we have the exact version when it was introduced. Thus if you change it to make it obvious that it's from an older version I have no problems with that.