On Fri, Jun 04, 2021 at 03:46:59PM +0100, Daniel P. Berrangé wrote: > +================================================= > +Libvirt Go Language API (semver, with Go modules) > +=================================================
"with Go modules support", perhaps? > +The `Go <https://golang.org/>`__ package ``libvirt.org/go/libvirt`` provides > +`CGo <https://golang.org/cmd/cgo/>`__ binding from the OS native Libvirt API. > + > +This package replaces the original `libvirt-go <../libvirt-go.html>`__ I would go with the original canonical (though not enforced) import path here, so "libvirt.org/libvirt-go" instead of just "libvirt-go". > +package in order to switch to using `semver <https://semver.org/>`__ and > +`Go modules <https://golang.org/ref/mod>`__. Aside from the changed > +import path ... and the different versioning scheme, ... > the API is fully compatible with the original package. [...] > +=============================================== > +Libvirt Go Language API (calver, no Go modules) > +=============================================== I don't think "calver" is as immediately understood as "semver". I would keep things simple and just write "obsolete" here. > The `Go <https://golang.org/>`__ package ``libvirt.org/libvirt-go`` provides > `CGo <https://golang.org/cmd/cgo/>`__ binding from the OS native Libvirt API. > > +This package is replaced by the new `libvirt <go/libvirt.html>`__ > +package in order to switch to using `semver <https://semver.org/>`__ and > +`Go modules <https://golang.org/ref/mod>`__. Aside from the changed > +import path, the new package API is fully compatible with this original > +package. I would prefer to have much stronger wording here, along the lines of The `Go <https://golang.org/>`__ package ``libvirt.org/libvirt-go`` has been replaced by the new `libvirt.org/go/libvirt <go/libvirt.html>` package and is now considered obsolete. Software using the old package will keep working, but no further development will happen on it; in particular, libvirt APIs introduced after 7.4.0 are never going to be available to users of the old package. If your application uses the old ``libvirt.org/libvirt-go`` package, we strongly encourage you to migrate to the new ``libvirt.org/go/libvirt`` package: as the new package is fully backwards compatible with the old one, this should be as easy as changing all occurrences of the import path. Since the technical part of the patch is solid, if you'd rather avoid respinning and would prefer me to propose these changes as follow-up adjustments, you can consider your version Reviewed-by: Andrea Bolognani <abolo...@redhat.com> and push it without any further ado :) -- Andrea Bolognani / Red Hat / Virtualization
