[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

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

  • To: Nick Rosbrook <rosbrookn@xxxxxxxxx>
  • From: George Dunlap <George.Dunlap@xxxxxxxxxx>
  • Date: Tue, 12 May 2020 17:20:08 +0000
  • Accept-language: en-GB, en-US
  • Authentication-results: esa2.hc3370-68.iphmx.com; dkim=none (message not signed) header.i=none; spf=None smtp.pra=George.Dunlap@xxxxxxxxxx; spf=Pass smtp.mailfrom=George.Dunlap@xxxxxxxxxx; spf=None smtp.helo=postmaster@xxxxxxxxxxxxxxx; dmarc=pass (p=none dis=none) d=citrix.com
  • Cc: Nick Rosbrook <rosbrookn@xxxxxxxxxxxx>, xen-devel <xen-devel@xxxxxxxxxxxxxxxxxxxx>, Wei Liu <wl@xxxxxxx>, Ian Jackson <Ian.Jackson@xxxxxxxxxx>
  • Delivery-date: Tue, 12 May 2020 17:21:08 +0000
  • Ironport-sdr: puPhiaKIFfltbd3Jd+DFXII/F/u6J0arkaLVLJtPPootupbEL+p1C1LwNu5daRrnIFoo+8ERlC eboSZutgWyjLkHRazGGqUk13arY05bvggI2TWF3I9mhX6czwNbaPgXTPwLpGyAPWy8Lh/yw7rP FkLuBFa0zTJtmWnN0AOyJOCE/cjlCLRk2UA6ylloTA1F7SKeEDEozKnyZr6IGGuXeoju6Zrp2y iDJe9dvuylw/k+a4zGvORq8ikxz5pn15pxfIXiEFrRJ8iCNU8oU8aSgBIIxc8EgE2NVip3Rxey rgs=
  • List-id: Xen developer discussion <xen-devel.lists.xenproject.org>
  • Thread-index: AQHWHzfORxaz+/l/VEu6tN0ApHJiJKikozQA
  • Thread-topic: [PATCH 3/3] golang/xenlight: add necessary module/package documentation

> 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 

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?




Lists.xenproject.org is hosted with RackSpace, monitoring our
servers 24x7x365 and backed by RackSpace's Fanatical Support®.