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.

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.

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.

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.

> 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

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. > > 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. > > 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. The third problem with it is that the python bindings require that this file accurately reflect the public API, so if this doesn't auto-build, people don't see the missing functions in the python binding when doing new work. eg I completely forgot about python binding for the data streams work until Chris happened to notice it after libvirt-api.xml got rebuilt for him

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.