189154 - XML bug retrieval needs documentation

Status: RESOLVED WONTFIX

(Bugzilla :: Documentation, defect, P2)

Description

[Dave Miller [:justdave]]

I'm not sure if the XML stuff even had docs to begin with.  If it didn't, it
needs it.  If it did, bug 136603 just added new features to it that need to be
documented.

Comment 1

[Bradley Baetz (:bbaetz)]

The doc was mozbot, I believe :) But thats old (Hixie hasn't reviewed the latest
version yet), and I suppose I should update it at some point to use bug 136603's
stuff.

Comment 2

[Dave Miller [:justdave]]

Jake is leaving for a while (Reserve unit got called up), and we don't have a
new docs owner yet.  Anyone interested in helping out, please add
[e-mail] to your watch list in your email preferences in Bugzilla.

Comment 3

[Colin Ogilvie [:cso]]

Attachment: Patch v1

Patch v1

Documents how to obtain the XML information from Bugzilla.

I figure I should probably document the format of the XML, but am not sure its
needed.

Comment 4

[Colin Ogilvie [:cso]]

For the HTML version of this page, please see
http://landfill.bugzilla.org/csodocs/testing/bugs-as-xml.html

Comment 5

[Vlad Dascalu]

Comment on attachment 188989 [details] [diff] [review]
Patch v1

Sorry for the delay. This looks good and ready to go in.

I have a couple of nits, but all of them are optional.

The reason for review- is the fact that this is non-commitable: like you can
see in the .html that you generated, the Mozbot link doesn't appear. In

+    <ulink href="http://www.mozilla.org/projects/mozbot/"/>)

you should replace href with url since that's the correct parameter for it.

And now for the mighty optional nits :)

Nit: do we want a dot at the end of the last three sentences listed below? :

+	
<para><filename>show_bug.cgi?ctype=xml&amp;id=1000&amp;excludefield=long_desc</
filename>
+	 - retrieve the XML content for bug 1000, exlcluding the long_desc
column
+	 (as used by Mozbot)</para>
+	 <para><filename>show_bug.cgi?ctype=xml&amp;id=1000</filename> -
retrieve
+	 the entire XML content for bug 1000</para>
+	
<para><filename>show_bug.cgi?ctype=xml&amp;id=1000&amp;id=2000&amp;field=bug_id
&amp;field=delta_ts</filename>
+	 - retrieve the bug_id and last changed time for bugs 1000 and
2000</para>


Nit: Section 14.1.2 is not logically contained because I have to look in 14.1.3
to find out that the parameter in the URL is called excludefield. Also I can
only assume that includefield exists as well, although I don't see it in the
documentation. I guess we can leave those out, but it would be nice to note
includefield and excludefield in 14.1.2.


Nit: The strangest sentence for me, a non-native English speaker, was this:

>> will only return data through the XML interface that the user that is running is able to see. <<

Maybe we should say that it will only return data that the user is authorized
to see? Although probably your sentence sounds more accurate.

Comment 6

[Colin Ogilvie [:cso]]

I'll prepare a new patch in the next few days...

(In reply to comment #5)
> I have a couple of nits, but all of them are optional.
> 
> The reason for review- is the fact that this is non-commitable: like you can
> see in the .html that you generated, the Mozbot link doesn't appear. In
> 
> +    <ulink href="http://www.mozilla.org/projects/mozbot/"/>)
> 
> you should replace href with url since that's the correct parameter for it.

Whoops, thats what you get for copying from an HTML document :)

> Nit: do we want a dot at the end of the last three sentences listed below? :
> 
> +	
> <para><filename>show_bug.cgi?ctype=xml&amp;id=1000&amp;excludefield=long_desc</
> filename>
> +	 - retrieve the XML content for bug 1000, exlcluding the long_desc
> column
> +	 (as used by Mozbot)</para>
> +	 <para><filename>show_bug.cgi?ctype=xml&amp;id=1000</filename> -
> retrieve
> +	 the entire XML content for bug 1000</para>
> +	
> <para><filename>show_bug.cgi?ctype=xml&amp;id=1000&amp;id=2000&amp;field=bug_id
> &amp;field=delta_ts</filename>
> +	 - retrieve the bug_id and last changed time for bugs 1000 and
> 2000</para>

I'm not particularly fussed one way or the other... I guess technically it
should have a . though since they are sentences to an extent...

> Nit: Section 14.1.2 is not logically contained because I have to look in 14.1.3
> to find out that the parameter in the URL is called excludefield. Also I can
> only assume that includefield exists as well, although I don't see it in the
> documentation. I guess we can leave those out, but it would be nice to note
> includefield and excludefield in 14.1.2.

Yes, that would make sense...

> Nit: The strangest sentence for me, a non-native English speaker, was this:
> 
> >> will only return data through the XML interface that the user that is
running is able to see. <<
> 
> Maybe we should say that it will only return data that the user is authorized
> to see? Although probably your sentence sounds more accurate.

It makes absolutely no sense to me, and I wrote it... your suggestion makes more
sense.

Comment 7

[Frédéric Buclin]

(In reply to comment #6)
> I'll prepare a new patch in the next few days...

How many days is "next few days" in UK? ;)

Comment 8

[Ray Booysen]

Colin, if you're too busy, I'll do the updates for you.

Comment 9

[Colin Ogilvie [:cso]]

(In reply to comment #7)
> How many days is "next few days" in UK? ;)

Helps if you don't forget

(In reply to comment #8)
> Colin, if you're too busy, I'll do the updates for you.

Go ahead...

Comment 10

[Ray Booysen]

Assigning to myself.  I'll have a patch "in a few days" :)

Just kidding. should be tomorrow.

Comment 11

[Ray Booysen]

Attachment: Patch v2

v2 of the patch.  Hopefully all of the nits are satisifed. 

Review requested.

Comment 12

[Ray Booysen]

Comment on attachment 208216 [details] [diff] [review]
Patch v2

Cancelling review.  Need to fix a few mistakes

Comment 13

[Ray Booysen]

Which branch must this this patch be applied against?

Comment 14

[Ray Booysen]

OK, I can't get Patch v1 to apply against 1.33 of using.xml.  Help?

Comment 15

[Frédéric Buclin]

(In reply to comment #14)
> OK, I can't get Patch v1 to apply against 1.33 of using.xml.  Help?

Copy and paste the text in the new using.xml. It's a single block. This should work fine.

Comment 16

[Frédéric Buclin]

Bugzilla 2.20 is no longer supported. Retargetting to 2.22.

Comment 17

[Frédéric Buclin]

Bugzilla 2.22 is no longer supported.

Comment 18

[Gervase Markham [:gerv]]

Getting bugs via XML still works, but any new software written to request data from Bugzilla should be using the API. So I don't think we should or need to document the legacy XML template.

Gerv