[Nmc-wg] Result Code Redux - One last issue

Thu Sep 29 07:27:46 CDT 2011

Hi Roman;

I removed the sentence from the document proposing '/beta'.  Thanks;

-jason

On 9/29/11 8:19 AM, thus spake Roman Łapacz:
> W dniu 2011-09-29 13:44, Jason Zurawski pisze:
>> Hi Michael;
>>
>> Thank you for providing the document. I don't agree at all with your
>> proposal, and feel that the original is much better for our needs. I
>> prefer to keep the status codes the same as the namespaces (using the
>> date as a version string at the end) for all the same reasons we have
>> constructed the namespaces in this pattern. You can read this
>> justification in the NM document.
>>
>> Its not for me to judge which is best though, I will send out a doodle
>> vote poll later today so we can pick one, and move on with the document.
>>
>> Regarding your observation that we went with '2.0' for NMWG - this was
>> chosen in 2004 before we had a lot of experience in using namespaces
>> and the complications we had in establishing new versions. In 2007 we
>> realized that appending a date was much easier, particularly when the
>> schema was changing frequently. I would prefer to use dates, and I
>> would prefer they stay at the end of the string to foster
>> extensibility and short/circuit identification of a general concept.
>
> I'm fine to use dates but Michael's comments convinced me that a strict
> rule how such date version is constructed should be documented in the
> doc (now it says about a string and there are two examples). Again, I
> would drop optional testing version part (e.g. "/beta"; instead we could
> have 20110920-beta or 20110920.beta or 20110920beta - to be selected).
>
> Cheers,
> Roman
>
>>
>> -jason
>>
>> On 9/28/11 7:08 AM, thus spake Michael Bischoff:
>>> Alright jason, for review:
>>>
>>> Also updated the examples. (ps it's interesting that we went with 2.0
>>> for nmwg)
>>>
>>> * kept the date as version. (didn't feel strongly about changing this
>>> also since it is now easy to detect the version we can opt to not
>>> redefine unchanged parts in future versions which probably removes any
>>> burden that changing it aims to solve)
>>> * moved the version to the left.
>>> * updated text
>>>
>>> to elaborate on the last email:
>>> "Client applications should be advised that parsing an error code may
>>> result in seeing this ‘unexpected’ last part, and could terminate
>>> parsing up to this point to avoid a complete failure." If the version
>>> is at the end it also get's dropped.
>>>
>>> Michael
>>>
>>> On Wed, Sep 28, 2011 at 12:01 PM, Jason
>>> Zurawski<zurawski at internet2.edu> wrote:
>>>> Hi Michael;
>>>>
>>>> If you feel strongly about this proposal, I will ask you to prepare
>>>> a formal document so we can review as a group. Please do so by
>>>> Friday of next week however, as we cannot continue to debate this
>>>> issue.
>>>>
>>>> Thanks;
>>>>
>>>> -jason
>>>>
>>>> ----- Original Message -----
>>>> From: Michael Bischoff<Michael.bischoff at controplex.nl>
>>>> To: zurawski at internet2.edu
>>>> Cc: Roman Łapacz<romradz at man.poznan.pl>, nmc-wg at ogf.org
>>>> Sent: Wed, 28 Sep 2011 05:18:08 -0400 (EDT)
>>>> Subject: Re: [Nmc-wg] Result Code Redux - One last issue
>>>>
>>>> Hello all,
>>>>
>>>> I wanted to post this earlier but didn't got around to it,
>>>>
>>>> Perhaps something to consider: having the version at the end makes it
>>>> more difficult to change the structure and to support multiply
>>>> versions in one client/service, especially if you don't force it to be
>>>> strictly a last single part:
>>>>
>>>> "http://schemas.ogf.org/nmc/status/"<STATUS_CATEGORY>"/"<STATUS_NAME>"/"<VERSION>"
>>>>
>>>>
>>>> and
>>>>
>>>> 201109/beta -> 201109.beta or 201109-beta (mandate that the version
>>>> bit will not consist out of '/' I would also recommend standardizing
>>>> the separation sign for this)
>>>> (ps don't think we need a day in there unless you want to make
>>>> multiply updates in a single month - which seems unlikely.)
>>>>
>>>> From a easy-to-parse point of view:
>>>> We need the version first to establish if we can interpret the status
>>>> regardless if the status we encounter is known. As such the version is
>>>> a more significant bit then what is currently left to it, as such I
>>>> would not put it at the end. Also client programmers might be tempted
>>>> to ignore the version bit given the version is at the end or least
>>>> significant spot, esp since we allow them to already ignore certain
>>>> preceding parts. Ignoring the version will lead to poorly functioning
>>>> clients. Moving the version to the left doesn't prevent this but does
>>>> require them to actively ignore it while at the same time doesn't
>>>> force them to do more work to ignore it.
>>>>
>>>> "http://schemas.ogf.org/nmc/status/"<VERSION>"/"<STATUS_CATEGORY>"/"<STATUS_NAME>"/
>>>>
>>>> (or do we tie things to a version of nmc as a whole:
>>>> "http://schemas.ogf.org/nmc/"<VERSION>"/status/"<STATUS_CATEGORY>"/"<STATUS_NAME>"/
>>>>
>>>> ?
>>>>
>>>> Also dates are good and bad - for example with dates you can't declare
>>>> forwards compatibility - 1.0 1.1, 1.2 - structure stayed the same all
>>>> messages in 1.0 are available in 1.1 1.2. So if you encounter a known
>>>> status and only the last part has changed it's safe to interpret. 1.0
>>>> -> 2.0 semantics and or structure has changed. Then again - forcing
>>>> clients to update might not be a bad thing at all.
>>>>
>>>> Best regards,
>>>>
>>>> Michael
>>>>
>>>> On Wed, Sep 28, 2011 at 10:20 AM, Jason
>>>> Zurawski<zurawski at internet2.edu> wrote:
>>>>> Hi Roman;
>>>>>
>>>>> Thanks for doing this, I will try to send an updated version by the
>>>>> end
>>>>> of the week, and include this in the formal document. Thanks;
>>>>>
>>>>> -jason
>>>>>
>>>>> On 9/27/11 12:32 PM, thus spake Roman Łapacz:
>>>>>> W dniu 2011-09-23 14:22, Jason Zurawski pisze:
>>>>>>> Hi Roman;
>>>>>>>
>>>>>>> I think this is a good idea, would you be able to make the
>>>>>>> changes to
>>>>>>> the document and sent it back to the list?
>>>>>>
>>>>>> Attached (needs polishing).
>>>>>>
>>>>>> Cheers,
>>>>>> Roman
>>>>>>
>>>>>>>
>>>>>>> Thanks;
>>>>>>>
>>>>>>> -jason
>>>>>>>
>>>>>>> On 9/23/11 12:29 PM, thus spake Roman Łapacz:
>>>>>>>> W dniu 2011-09-23 11:32, Jason Zurawski pisze:
>>>>>>>>> Gang;
>>>>>>>>
>>>>>>>> Hi,
>>>>>>>>
>>>>>>>>>
>>>>>>>>> In typing up the final version of the status codes into the
>>>>>>>>> document,
>>>>>>>>> I hit upon a snag. Here is an example of what was proposed in the
>>>>>>>>> prior mail:
>>>>>>>>>
>>>>>>>>> http://schemas.ogf.org/nmc/2011/09/status/informational/protocol
>>>>>>>>> version/
>>>>>>>>>
>>>>>>>>> This goes against our typical method of constructing namespaces. I
>>>>>>>>> would suggest we do this instead:
>>>>>>>>>
>>>>>>>>> http://schemas.ogf.org/nmc/status/informational/protocol
>>>>>>>>> version/2011/09/
>>>>>>>>>
>>>>>>>>> Or even better using:
>>>>>>>>>
>>>>>>>>> 201109
>>>>>>>>>
>>>>>>>>> or
>>>>>>>>>
>>>>>>>>> 20110923
>>>>>>>>
>>>>>>>> Right. Good you spotted this. I prefer to have just one field for
>>>>>>>> version number (201109 or 20110923) with an exception for early
>>>>>>>> testing
>>>>>>>> versions (201109/beta or 20110923/beta).
>>>>>>>>
>>>>>>>>>
>>>>>>>>> As the 'version' string. I am attaching an updated document going
>>>>>>>>> with the first suggestion, I prefer the last best of all. Other
>>>>>>>>> opinions?
>>>>>>>>
>>>>>>>> What do you think to replace the code hierarchy with the pattern
>>>>>>>> in the
>>>>>>>> beginning of section 2. Example:
>>>>>>>>
>>>>>>>> --example---------------------
>>>>>>>>
>>>>>>>> "http://schemas.ogf.org/nmc/status/"<STATUS_CATEGORY>"/"<STATUS_NAME>"/"<VERSION>
>>>>>>>>
>>>>>>>>
>>>>>>>>
>>>>>>>> <STATUS_CATEGORY> may have the following text values:
>>>>>>>> - informational
>>>>>>>> - successful
>>>>>>>> - redirection
>>>>>>>> - clienterror
>>>>>>>> - servererror
>>>>>>>>
>>>>>>>> <STATUS_NAME> depends on the status category and may have the
>>>>>>>> following
>>>>>>>> text values:
>>>>>>>> - informational category
>>>>>>>> -- protocol version
>>>>>>>> -- data limitation
>>>>>>>> -- service_contact
>>>>>>>> - client error category
>>>>>>>> -- bad_message
>>>>>>>> -- bad request
>>>>>>>> -- authentication_failed
>>>>>>>> -- unauthorized
>>>>>>>> -- message not allowed
>>>>>>>> -- event_type_not_allowed
>>>>>>>> -- event_type_not_allowed
>>>>>>>> -- request_too_large
>>>>>>>> -- request_timeout
>>>>>>>> -- protocol_not_allowed
>>>>>>>> -- chaining_not_understood
>>>>>>>> - servererror category
>>>>>>>> -- data_fetch_error
>>>>>>>> -- too_busy
>>>>>>>> -- administrative_down
>>>>>>>> Two categories, successful and redirection, do not need to have
>>>>>>>> certain status names.
>>>>>>>>
>>>>>>>> VERSION is a string presenting information about the version of
>>>>>>>> protocol, e.g. 201109 or 20110925. In case of early testing
>>>>>>>> version an
>>>>>>>> optional part after "/" may be added (e.g. 201109/beta or
>>>>>>>> 20110925/beta) .
>>>>>>>>
>>>>>>>> -- end---------------------
>>>>>>>>
>>>>>>>> I'm thinking about such update because version numbers don't
>>>>>>>> look good
>>>>>>>> in the structure. They are not generic. The use of pattern
>>>>>>>> solves this
>>>>>>>> issue. What do you think? (of course a short description below the
>>>>>>>> pattern in my example may be done much better; I just wanted to
>>>>>>>> present
>>>>>>>> my idea).
>>>>>>>>
>>>>>>>> Cheers,
>>>>>>>> Roman
>>>>>>>>
>>>>>>>>>
>>>>>>>>> Thanks;
>>>>>>>>>
>>>>>>>>> -jason