[MOBY-dev] RFC #1863 Error Handling in MOBY-S -- Vote Called

[David González Pisano]

I think we can still vote today, as far as Martin's objections are not 
really about the proposal itself, but about the aesthetics and 
presentation of the proposal. My solutions below

Martin Senger escribió:

>>The vote has been called.  Voting members may vote by adding their YES 
>>(accept)  or NO (do not accept) to the comments history  through Bugzilla
>>
>>Voting ends Sept 26th
>>
>>    
>>
>    I propose to extend the vote deadline to October 15th. Reasons are:
>
>   1) The proposal (as available from Bugzilla) is still too complex, full
>of explanaition, and it is not clear what is a discussion and what is a
>proposal. I recommend that the authors take away most of the reasoning and
>just state what is the new API. (The reasoning can come later back to the
>documentation, if Frank, as a document-manager, decides so.)
>
>  
>
Explanations would not make the document *more* difficult to understand 
(unless the explanations are wrong)? Probably you are refering to the 
motivation / discussion parts, that we understand we needed to explain 
our reasons to expand MOBY-S specification. I've rewritten the proposal 
so now is just a specification extension proposal (still not an API 
proposal, that's the next implementation step).

>   2) The proposal is in the format which is not readable for everyone
>(for example, using OpenOffice mixes the tables on the first page, so I do
>not understand what they mean and why they are there). Open source API
>should use open documentation tools, as much as it can. The whole Biomoby
>API/docs is, so far, written in non-proprietary document format, so I
>suggest to continue with it.
>  
>
See, we can choose between PDF, RTF, ASCI text, HTML, OpenOffice 
format... We've never talked about this before, and the document can 
easily be exported to whatever format we agree. I am not really 
concerned about using open or closed tools, OMG publishes specifications 
in Word format -between other- and schema documentation using XML Spy 
and nobody objects using commercial tools as far as everybody can 
understand them. Never mind.

Anyway I don't have access to the bugzilla, and I think we still not 
agreed on any format, so please let me what format do you want and I'll 
be happy to send it to Frank to attach it to bugzilla. BTW, how do i 
access to the bugzilla? :-)

>   3) The error codes are still not explained enough. I suggest either
>remove (some of) them, or document them better. Especially the client-side
>errors are still obscure to me.
>  
>
Do you have any specific proposal here? We don't see any major problems, 
but probably we are missing something. Just for clarity, I've removed 
the 800 section (client errors). The proposal (like the LSAE one) is 
open to add new error codes, so this is expandable in the future if we 
agree that we need (or not) specific error codes.

>   4) The proposal is not clear how to integrate new XML tags in
>serviceNotes with the current usage of serviceNotes. The current usage is
>a free text: should this free text be expected before, or after the
>exception code? Should it be there either exception tags or classic notes
>text? This would be the only place in Biomoby API with XML-mixed element,
>so it needs to be clarified, an example showing all possibilities would be
>beneficial.
>  
>
Added a new optional Notes element under serviceNotes to separate human 
readable free text from structured XML mobyException. This way we can 
maintain old functionality into serviceNotes. API changes proposed too.

>   5) The proposal should clearly suggest what (if anything) should be
>removed from the current Biomoby API. I mean the fact that the current API
>(even perhasp not literally, but surely by spirit) expects (allows) an
>empty result in case of an error (e.g. an ID cannot be found in a target
>database). Will this still be valid, or should serviceNotes be returned
>instead?
>  
>
Added a new section with API changes needed. Your question was answered 
in the proposal which is in the bugzilla but in short yes, still an 
empty result has to be sent and (optionally) a serviceNotes with an 
exception be reported with it. This allows the error handling system to 
be compatible with old clients.

>   I already said that I liked the new proposal and I am going to support
>it - but I want to introduce new things into Biomoby API as precisely as
>we can. Therefore, I am not ready to vote yet. But just in case, my
>suggestion described above, will not be accepted, and the vote deadline
>announced by Mark will not be moved, I vote NO. (Sorry, I do not want to
>do it on Bugzilla, because (a) I think that this NO is only temporary and
>conditionally, and (b) I did not found any "history comments" there so I
>would not know how to use Bugzilla for that.)
>
>  
>
Hope that you change your mind. As soon as you tell me which document 
format you want, I'll send the latest version with the changes commented 
above.

>   Regards,
>   Martin
>
>  
>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: dgpisano.vcf
Type: text/x-vcard
Size: 338 bytes
Desc: not available
URL: <http://lists.open-bio.org/pipermail/moby-dev/attachments/20050926/ab68c498/attachment-0001.vcf>