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

[Peter Krempa]

On Tue, Apr 19, 2022 at 15:17:07 +0200, Victor Toso wrote:
> Hi,
> 
> 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:
> > > Minor hand adjustments around syntax, not the metadata per se.
> > > 
> > > Signed-off-by: Victor Toso <victortoso at redhat.com>
> > > ---
> > >  include/libvirt/libvirt-domain-checkpoint.h |  28 +-
> > >  include/libvirt/libvirt-domain-snapshot.h   |  60 +-
> > >  include/libvirt/libvirt-domain.h            | 877 +++++++++++---------
> > >  include/libvirt/libvirt-host.h              |  36 +-
> > >  include/libvirt/libvirt-interface.h         |   4 +-
> > >  include/libvirt/libvirt-network.h           |  50 +-
> > >  include/libvirt/libvirt-nodedev.h           |  54 +-
> > >  include/libvirt/libvirt-nwfilter.h          |   4 +-
> > >  include/libvirt/libvirt-secret.h            |  10 +-
> > >  include/libvirt/libvirt-storage.h           |  96 ++-
> > >  include/libvirt/virterror.h                 | 394 ++++-----
> > >  11 files changed, 877 insertions(+), 736 deletions(-)
> > 
> > [...]
> > 
> > >  
> > >  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.