On Fri, Oct 02, 2009 at 12:16:36PM +0100, Daniel P. Berrange wrote: > On Thu, Oct 01, 2009 at 01:33:50PM +0200, Daniel Veillard wrote: > > On Thu, Oct 01, 2009 at 12:32:51PM +0200, Chris Lalancette wrote: > > > Matthias Bolte wrote: > > > > Commit 47c8709564ac3f2ec5b4a3830ac213e69b4a44d5 "Fix up a few typos in > > > > the tree" triggered changes in docs/libvirt-api.xml and > > > > docs/libvirt-refs.xml. The attached patch contains this changes. > > > > > > > > The files docs/libvirt-api.xml and docs/libvirt-refs.xml are generated > > > > by apibuild.py, why are this generated files under version control? > > > > > > Yeah, I've been running into this too. I think we should remove those files > > > from version control, personally. > > > > I don't care about docs/libvirt-refs.xml, but I would prefer to keep > > docs/libvirt-api.xml in the tree for the reasons exposed during the big > > reshuffling. > > The problem is that now this is systematically rebuilt on make > > while it used to be rebuilt only on a specific "make rebuild" target > > in doc, this was done for example on "make dist", this is why so many > > people start to see diffs. > > There's a couple of problems here > > I did not intentionally change it to be re-generated everytime, but it > is being done as a side-effect of building the HTML files. ie the > html/index.html file which is the website page for the API, has a > dependancy on libvirt-api.xml, so make checks if it is up2date and if > not regenerates the API file. IMHO there is no need to regenerate the web site all the time either Only when we know there is a documentation change or a real API addition. > The second issue is a bug in apibuild.py which tries to sort the > element in the XML file, but after calling sort() in the list, it > then calls uniq() which messes up sorting again. So the XML file > ends up different everytime anyone builds it. hum, that should be fixed, > Even without that bug we constantly see changes which cause the > re-generation of this file - eg when commiting new APIs like > Chris' migration ones people always forget to manually re-generate > the XML file before commiting. Or when fixing typos in the libvirt.c > function comments, etc people forget to re-generate. This really > says to me that we should not be storing this XML file in GIT, since > every one of us constantly forgets to update it manually. Well it's not about forgetting, it's that usually this is not immediately needed, and if needed "cd docs ; make rebuild" was simple enough. I was doing that when needed, and it wasn't affecting the majority of the people developping patches. > > I would really prefer to go back to the old way of only building it > > when needed instead of systematically, this would avoid the problem > > most people are facing while still allow me to monitor closely changes > > to the generated API. > > Changes in this libvirt-api.xml file don't have any impact of the API > or ABI. It is just a side-effect of changes to the real important > API files of include/libvirt/libvirt.h, and src/libvirt.c It change the way we present the docs on the web site and the python bindings, but ultimately it is good for me to have a single resource to check, for example when getting ready to push a release. Daniel -- Daniel Veillard | libxml Gnome XML XSLT toolkit http://xmlsoft.org/ daniel@xxxxxxxxxxxx | Rpmfind RPM search engine http://rpmfind.net/ http://veillard.com/ | virtualization library http://libvirt.org/ -- Libvir-list mailing list Libvir-list@xxxxxxxxxx https://www.redhat.com/mailman/listinfo/libvir-list