Re: [PATCH 3/3] golang/xenlight: add necessary module/package documentation

[George Dunlap <George.Dunlap@xxxxxxxxxx>]

> On Apr 30, 2020, at 10:39 PM, Nick Rosbrook <rosbrookn@xxxxxxxxx> wrote:
> 
> Add a README and package comment giving a brief overview of the package.
> These also help pkg.go.dev generate better documentation.
> 
> Also, add a copy of Xen's license to tools/golang/xenlight. This is
> required for the package to be shown on pkg.go.dev and added to the
> default module proxy, proxy.golang.org.

libxl is actually under the LGPL; I guess we want the xenlight package to be 
the same?

As discussed before, arguably distributing the *.gen.go files won’t be 
sufficient to comply with the license, because they are not the “preferred form 
of modification”: that would be libxl_types.idl, along with the python 
generators.

OTOH, I suppose that’s sort of Google’s problem in some ways...

> 
> diff --git a/tools/golang/xenlight/README.md b/tools/golang/xenlight/README.md
> new file mode 100644
> index 0000000000..42240e2132
> --- /dev/null
> +++ b/tools/golang/xenlight/README.md
> @@ -0,0 +1,17 @@
> +# xenlight
> +
> +## About
> +
> +The xenlight package provides Go bindings to Xen's libxl C library via cgo. 
> The package is currently in an unstable "preview" state.

We should probably try to slot it into one of the official terms we use in 
SUPPORT.md (and also add it to SUPPORT.md!).

ATM you can’t even do a full VM lifecycle with it properly (to include 
harvesting destroyed domains); so I think it would come under “experimental”.

> This means the package is ready for initial use and evaluation, but is not 
> yet fully functional. Namely, only a subset of libxl's API is implemented, 
> and breaking changes may occur in future package versions.
> +
> +Much of the package is generated using the libxl IDL. Changes to the 
> generated code can be made by modifying `tools/golang/xenlight/gengotypes.py` 
> in the xen.git tree.
> +
> +## Getting Started
> +
> +```go
> +import (
> +        "xenbits.xen.org/git-http/xen.git/tools/golang/xenlight"
> +)
> +```
> +
> +The module is not yet tagged independently of xen.git, so expect to see 
> `v0.0.0-<date>-<git hash>` as the package version. If you want to point to a 
> Xen release, such as 4.14.0, you can run `go get 
> xenbits.xen.org/git-http/xen.git/tools/golang/xenlight@RELEASE-4.14.0`.

I think I would say something like:

—

The module is not yet tagged independently of xen.git; if you don’t specify the 
version, you’ll get the most recent development version, which is probably not 
what you want.  A better option would be to specify a Xen release tag; for 
instance: `go get xenbits…./xenlight@RELEASE-4.14.10`.

—


> diff --git a/tools/golang/xenlight/xenlight.go 
> b/tools/golang/xenlight/xenlight.go
> index 6b4f492550..3eaa5a3d63 100644
> --- a/tools/golang/xenlight/xenlight.go
> +++ b/tools/golang/xenlight/xenlight.go
> @@ -14,6 +14,8 @@
>  * You should have received a copy of the GNU Lesser General Public
>  * License along with this library; If not, see 
> <http://www.gnu.org/licenses/>.
>  */
> +
> +// Package xenlight provides bindings to Xen's libxl C library.
> package xenlight


Will this comment replace the comment above it in the pkg.go.dev module page?

 -George