[libvirt] documentation request
I'd like to make a request to the people on here to change the way documentation is done when libvirt is changed. I'd love to see two things in the documentation with every change: 1) Version tracking -- every feature that's added should always list which version it was added in 2) Examples -- especially for the changes to domain XML, every new attribute should be demonstrated in the example box for that section To pick a random example, there's the new cpushares and vcpupin attributes. Looking here: http://libvirt.org/formatdomain.html#elementsResources neither of them is listed in the example box. vcpupin has a pretty complicated syntax, and the only way to figure out what it is is to dig through list archives. Also, users might become really confused when these features fail to do anything on versions of libvirt < 0.9.0. .... Actually, digging further I noticed that Osier Yang actually did write an example section: http://www.redhat.com/archives/libvir-list/2011-March/msg01342.html but it fell away by the time his change was pushed (commit 6b3644). --Igor
于 2011年05月12日 16:00, Igor Serebryany 写道:
I'd like to make a request to the people on here to change the way documentation is done when libvirt is changed. I'd love to see two things in the documentation with every change:
1) Version tracking -- every feature that's added should always list which version it was added in
2) Examples -- especially for the changes to domain XML, every new attribute should be demonstrated in the example box for that section
To pick a random example, there's the new cpushares and vcpupin attributes. Looking here: http://libvirt.org/formatdomain.html#elementsResources neither of them is listed in the example box. vcpupin has a pretty complicated syntax, and the only way to figure out what it is is to dig through list archives. Also, users might become really confused when these features fail to do anything on versions of libvirt< 0.9.0.
....
Actually, digging further I noticed that Osier Yang actually did write an example section: http://www.redhat.com/archives/libvir-list/2011-March/msg01342.html but it fell away by the time his change was pushed (commit 6b3644).
I'm surprised it fell away in the final patch, but anyway, it lacks the version info, and agree that with a version info will be nice, Thanks for pointing it out. Regards Osier
On Thu, May 12, 2011 at 03:00:17AM -0500, Igor Serebryany wrote:
I'd like to make a request to the people on here to change the way documentation is done when libvirt is changed. I'd love to see two things in the documentation with every change:
1) Version tracking -- every feature that's added should always list which version it was added in
"Feature" is an interesting one. For APIs (which are not really like features) there is a page that covers this. You'd be forgiven for not finding it since it took me about 10 minutes to find it: http://libvirt.org/hvsupport.html For features, the best you can do is probably look at the release notes: http://libvirt.org/news.html
2) Examples -- especially for the changes to domain XML, every new attribute should be demonstrated in the example box for that section
Agreed. Actually Justin was working on this documentation issue, but he's now doing Aeolus stuff. Patches are welcome of course. If you work out how to use those two APIs, you might as well update the virsh and/or API documentation by sending a patch. Going further, I think that patches that add new features but don't add sufficient documentation and examples should be rejected. Rich. -- Richard Jones, Virtualization Group, Red Hat http://people.redhat.com/~rjones New in Fedora 11: Fedora Windows cross-compiler. Compile Windows programs, test, and build Windows installers. Over 70 libraries supprt'd http://fedoraproject.org/wiki/MinGW http://www.annexia.org/fedora_mingw
participants (3)
-
Igor Serebryany -
Osier Yang -
Richard W.M. Jones