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

[Nick Rosbrook <rosbrookn@xxxxxxxxx>]

On Tue, May 12, 2020 at 1:20 PM George Dunlap <George.Dunlap@xxxxxxxxxx> wrote:
>
>
>
> > 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?

Thanks, yes it should probably 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...

Yeah, I guess that's true. Besides, modules are not intended to be
modified (they are store in a read-only cache by default), so I don't
think we need to worry about that until a separate repo is involved.
Anyone who looks on pkg.go.dev for now will see that xen.git is the
source repository.

> >
> > 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”.

Thanks, I wasn't aware of these definitions in SUPPORT.md.

> > 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`.

That sounds much better. Thanks.

> > 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?

Yes, this should be recognized as the "package comment" now.

-NR