[libvirt PATCH v2] docs: introduce stubs for new libvirt Go packages

[Andrea Bolognani]

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 <abologna at redhat.com>

and push it without any further ado :)

-- 
Andrea Bolognani / Red Hat / Virtualization