942599 - Documentation about possible_duplicates() lists 'products' as argument instead of 'product'

Status: RESOLVED FIXED

(Bugzilla :: WebService, defect)

Description

[Rob Snelders]

User Agent: Mozilla/5.0 (X11; Ubuntu; Linux x86_64; rv:25.0) Gecko/20100101 Firefox/25.0 (Beta/Release)
Build ID: 20131115105702

Steps to reproduce:

I want to get possible duplicates for a bug. As the instance has many different products I want to restrict it to 1 of the products.
So to the XML-RPC interface I sepcify a summary, an array with 1 product and a array with some fields I want to include. As that are the possible parameters summary, products and include_fields


Actual results:

I get results from multiple products.


Expected results:

Only bugs of the product I specified

Comment 1

[Frédéric Buclin]

(In reply to Rob Snelders from comment #0)
> parameters summary, products and include_fields

It must be 'product' singular, not plural. The documentation is wrong.

As this method accepts a list of products, I agree it would make more sense to have it plural, but that's how it has been implemented, see bug 22353.

Comment 2

[Frédéric Buclin]

glob: what's the rationale to spell 'product' singular for a parameter which takes a *list* of products? (you reviewed bug 22353)

As the method is marked UNSTABLE, shouldn't we fix that and mark 'product' (singular) as deprecated in 4.x, and use 'products' instead for 5.0?

Comment 3

[:glob ✱]

(In reply to Frédéric Buclin from comment #2)
> As the method is marked UNSTABLE, shouldn't we fix that and mark 'product'
> (singular) as deprecated in 4.x, and use 'products' instead for 5.0?

that sounds perfectly reasonable to me :)

Comment 4

[Frédéric Buclin]

Attachment: patch for trunk, v1

Comment 5

[:glob ✱]

Comment on attachment 8341137 [details] [diff] [review]
patch for trunk, v1

r=glob

Comment 6

[Frédéric Buclin]

Attachment: patch for 4.x

Fix the POD for 4.x.

Comment 7

[Frédéric Buclin]

It's not just a typo somewhere in the text. We are saying to developers to pass 'products' when it's really 'product'. That's exactly what this bug is about: someone passed 'products' and wondered why this param has been ignored.

Comment 8

[Dave Miller [:justdave]]

Honestly I'm shocked to see LpSolit fighting for this one as he was usually the one to deny such requests in the past ;)

But yes, I agree here, this is a correctness in documentation thing, and since our website docs are built from the POD in the library files, this is where we have to change it to fix the website.

Comment 9

[Frédéric Buclin]

(In reply to Dave Miller [:justdave] ([e-mail]) from comment #8)
> Honestly I'm shocked to see LpSolit fighting for this one as he was usually
> the one to deny such requests in the past ;)

I never denied approval for documentation stuff.

Comment 10

[Dave Miller [:justdave]]

(In reply to Frédéric Buclin from comment #9)
> I never denied approval for documentation stuff.

Maybe my memory sucks then.  Apologies if so.  I remember someone being stubborn about touching code files for any reason on security-only branches.

Comment 11

[Frédéric Buclin]

We will have to relnote in 5.0 that the list of parameters changed: product -> products.

Committing to: bzr+ssh://[e-mail]/bugzilla/trunk/
modified Bugzilla/WebService/Bug.pm
Committed revision 8825.

Committing to: bzr+ssh://[e-mail]/bugzilla/4.4/
modified Bugzilla/WebService/Bug.pm
Committed revision 8640.

Committing to: bzr+ssh://[e-mail]/bugzilla/4.2/
modified Bugzilla/WebService/Bug.pm
Committed revision 8241.

Committing to: bzr+ssh://[e-mail]/bugzilla/4.0/
modified Bugzilla/WebService/Bug.pm
Committed revision 7764.

Comment 12

[Frédéric Buclin]

Added to relnotes for 5.0rc1.