[libvirt] Update libvirt API and refs XML files
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? Matthias
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. -- Chris Lalancette
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. 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. Daniel -- Daniel Veillard | libxml Gnome XML XSLT toolkit http://xmlsoft.org/ daniel@veillard.com | Rpmfind RPM search engine http://rpmfind.net/ http://veillard.com/ | virtualization library http://libvirt.org/
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 Daniel -- |: Red Hat, Engineering, London -o- http://people.redhat.com/berrange/ :| |: http://libvirt.org -o- http://virt-manager.org -o- http://ovirt.org :| |: http://autobuild.org -o- http://search.cpan.org/~danberr/ :| |: GnuPG: 7D3B9505 -o- F3C9 553F A1DA 4AC2 5648 23C1 B3DF F742 7D3B 9505 :|
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@veillard.com | Rpmfind RPM search engine http://rpmfind.net/ http://veillard.com/ | virtualization library http://libvirt.org/
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 Daniel -- |: Red Hat, Engineering, London -o- http://people.redhat.com/berrange/ :| |: http://libvirt.org -o- http://virt-manager.org -o- http://ovirt.org :| |: http://autobuild.org -o- http://search.cpan.org/~danberr/ :| |: GnuPG: 7D3B9505 -o- F3C9 553F A1DA 4AC2 5648 23C1 B3DF F742 7D3B 9505 :|
On Fri, Oct 02, 2009 at 12:38:05PM +0100, Daniel P. Berrange wrote:
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
Okay, I surrender ... you can remove them from git ! Daniel -- Daniel Veillard | libxml Gnome XML XSLT toolkit http://xmlsoft.org/ daniel@veillard.com | Rpmfind RPM search engine http://rpmfind.net/ http://veillard.com/ | virtualization library http://libvirt.org/
On 10/02/2009 07:16 AM, Daniel P. Berrange wrote:
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.
Or some people (points at self) never knew it needed to be manually regenerated.
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 agree. Of course I'm in the camp of believing that there shouldn't be *any* generated files in git.
On 09/30/2009 08:41 PM, 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.
FYI: this patch is subsumed by mine which also fixes a few other typos. Paolo
participants (6)
-
Chris Lalancette -
Daniel P. Berrange -
Daniel Veillard -
Laine Stump -
Matthias Bolte -
Paolo Bonzini