Subject: Re: [Last-Call] [regext] Artart last call review of draft-ietf-regext-epp-registry-maintenance-17

From: Francesca Palombini <[email-masked]>
Date: Wed, 6 Oct 2021 18:29:27 +0000

Harald: thanks very much for the ART review. I have balloted DISCUSS while waiting for v-18 of the draft addressing your comments.

Authors: thank you for answering Harald’s points. I’m glad there has already been resolution and I’ll lift the DISCUSS once the update is published.

Francesca

From: last-call <[email-masked]> on behalf of Tobias Sattler <[email-masked]>
Date: Monday, 13 September 2021 at 15:07
To: Harald Alvestrand <[email-masked]>
Cc: Jody Kolker <[email-masked]>, [email-masked] <[email-masked]>, [email-masked] <[email-masked]>, [email-masked] <[email-masked]>, [email-masked] <[email-masked]>
Subject: Re: [Last-Call] [regext] Artart last call review of draft-ietf-regext-epp-registry-maintenance-17
Hi Harald,

Thank you for your swift feedback.

We have incorporated the changes on our GitHub repository (https://github.com/seitsu/registry-epp-maintenance/blob/master/draft-ietf-regext-epp-registry-maintenance.txt<https://protect2.fireeye.com/v1/url?k=bd553b6a-e2ce0268-bd557bf1-869a14f4b08c-b9ffb7d8b3e2a5e9&q=1&e=ded3691c-08dd-46b4-addf-ed7083f4a6fe&u=https%3A%2F%2Fgithub.com%2Fseitsu%2Fregistry-epp-maintenance%2Fblob%2Fmaster%2Fdraft-ietf-regext-epp-registry-maintenance.txt>).

If this version is fine for you, we will do the update on datatracker.

Best,
Tobias

On 13. Sep 2021, at 14:13, Harald Alvestrand <[email-masked]<mailto:[email-masked]>> wrote:

On 9/13/21 12:57 PM, Jody Kolker wrote:

Thanks Harald for the detailed review of the document.  Please see our comments in line below.

Thanks again!
Jody Kolker

-----Original Message-----
From: Harald Alvestrand via Datatracker <[email-masked]<mailto:[email-masked]>>
Sent: Monday, September 13, 2021 3:14 AM
To: [email-masked]<mailto:[email-masked]>
Cc: [email-masked]<mailto:[email-masked]>; [email-masked]<mailto:[email-masked]>; [email-masked]<mailto:[email-masked]>
Subject: Artart last call review of draft-ietf-regext-epp-registry-maintenance-17

Caution: This email is from an external sender. Please do not click links or open attachments unless you recognize the sender and know the content is safe. Forward suspicious emails to isitbad@.

Reviewer: Harald Alvestrand
Review result: Almost Ready

I have reviewed this document as part of the ARTART review team.

Verdict: Almost ready
There are a few things that need better definitions to be comprehensible enough for interoperable implementation. There is also one confusing formatting error that should be fixed before publication.

Weak definitions:

- "Maintenance event" is never defined. From context, it is possible to infer that a maintenance event refers to some service being partially or wholly unavailable in the time interval given; given that this is the whole point of the document, this should be explicit.

<<
We will add the following to the first paragraph under "1. Introduction"

"Registries routinely update systems to ensure a higher quality of service, implement new services, or upgrade protocols to the newest standards.  These updates are pushed to various registry environments during time frames that are communicated to registrars as "maintenance events".  Registries usually inform registrars for maintenance events in various formats, none of which …..

Very much more informative!

I'd add "This may require making services unavailable for some limited time while the upgrade happens." Hitless upgrades are known technology, but quite complex and not possible in all places - the text proposed seems to assume that all updates require maintenance events.

"
It should also be explicit that the service will be either fully and correctly available or not available at all, and that no harm (apart from being denied service) will come from trying to access the service in the maintenance interval; "maintenance" that, for instance, puts a test database up where the normal database is would be just a broken service, not "maintenance" in this sense. (If broken stuff might happen, I think you need a new impact value in addition to "full", "partial" or "none"
- something like "STAYAWAYYOUWILLREGRETEVENTHINKINGABOUTTRYING").

<<  In the case described above and any other similar maintenance events, the registry should not be allowing registrars to connect to the system by taking a "full" maintenance.  I don't believe we have ever experienced any maintenance event of the type described above.

I certainly hope not! Calling out that expectation may be good.

- "maint:connection" and "maint:implementation" make very little sense as described. They may refer to having to reconnect the EPP service or to upgrade the EPP schema in use, but since the "maint:name" element of "maint:system"
seems to encompass WHOIS and others, the actions that may be required are not clear; an instruction to "do something connection-related" cannot be interoperably implemented. Suggestion: Either delete these elements or (if intended to be consumed by a human) add the option to add a text description of what should be done.

<<  These flags are only meant to indicate that the registrar should review the maint:description element in the response for further details explaining actions the registrar will be effected by regarding the maintenance.  Adding a description to both of these elements seems to duplicate the information that should be in the maint:description element.  We would like to suggest this edit to the document:
From:
<maint:connection>
            The value SHALL be boolean and indicates if a client needs
            to do something that is connection-related, such as a
            reconnect.

         <maint:implementation>
            The value SHALL be boolean and indicates if a client needs
            to do something that is implementation-related, such as a
            code change.

To:
       <maint:connection>
            The value SHALL be boolean and indicates if a client needs
            to perform an action that is connection related, such as a reconnect.
The attribute should only be used as a flag to indicate connections
will be affected.  Servers SHOULD include a description of how the
connetions are affected in the <main:description> element above.

         <maint:implementation>
            The value SHALL be boolean and indicates if a client needs
            to do perform an action thate is implementation related,
such as a code change.   The attribute should only be used as a flag
to indicate connections will be affected.  Servers SHOULD include

was this meant to say "implementations will be affected"?

a description of how the implmenation is affected in the
<main:description> element above.
- pollType seems somewhat strange. The implicit definition seems to be that the client polls the server and the server replies with a list of outstanding maintenance events, with the value "create" returned the first time the server tells the client about the event. This implies that the server is required to keep state of what it has told each client about the event; same goes for event deletion. If such a state tracking requirement is indeed intended, this should be explicit.

<<
This type of tracking requirement was not intended.  Registries will not be expected to keep state of what each registrar has received as far as the type of maintenance events.

On reading RFC 5730, I see that the <poll> command has a queue of events that can be retrieved, which will then constitute the memory of what the client has received or not; if it's still in queue, it hasn't been received. And for this scheme to work at all, there has to be one distinct queue of notifications per client. In that context, the "pollType" sounds much more reasonable.

Consider this comment dropped.

Formatting issues:

In the list of elements in section 3, the indentation of <maint:environment> and the succeeding elements indicates that it is an element of <maint:systems>.
Examples indicate that it is an element of <maint:item>, which makes a lot more sense.

<<
Formatting will be updated.
Precision in definition issues:

The incantation "The extended date-time form using upper case "T" and "Z"
characters defined in ISO 8601 [RFC3339] MUST be used to represent date-time values." is not precise (I don't know if it's common) - it seems to claim that RFC 3339 is ISO 8601, which is just confusing. Suggested format: "The date-time format defined as "date-time" in [RFC3339], with time-offset="Z", MUST be used".

<<
Text will be updated.
Styllistic issues:

The cuteness of using "upDate" as both meaing "update" and "this is a date"
hurts the eyes :-) Unless there is tradition for this name, I'd suggest being boring and using "updateDate".

<<
This document is following the same pattern used to signify the date the state of a domain was updated,  <domain:update> from RFC 5731, which we considered to be the standard to be followed.

Ack! Tradition rules.

Having migration considerations before item descriptions looks a bit weird when reading the document top to bottom. Would it be nicer to move it after section 4?

<<
The document is following the same format that is used in RFC 8807 and RFC 8847 where migrations to the new version of the extension are covered immediately following the introduction.  However, we will update this document to move the migration section to after section 4 if this is what is needed.

Your call. If it is an existing tradition, you should decide whether it's a good tradition or a bad one.

I have not attempted to verify the schema, nor have I attempted to check the document against common styles for EPP extensions. If comments touch on things that are mandated by common EPP practices, feel free to consider these comments overridden.

Hope this is helpful.

_______________________________________________
regext mailing list
[email-masked]<mailto:[email-masked]>
https://www.ietf.org/mailman/listinfo/regext

---

From: Harald Alvestrand <[email-masked]>
Date: Thu, 7 Oct 2021 10:49:24 +0200

Apologies for the slow reply - I have reviewed the diff and found that 
it addresses my worries.

I now think this document is ready for publication. Thanks!

Harald

On 9/21/21 7:24 PM, Tobias Sattler wrote:
> Hi Harald,
>
> Just checking, are the changes on GitHub fine for you?
>
> Thanks,
> Tobias
>
>> Am 13.09.2021 um 15:06 schrieb Tobias Sattler <[email-masked]>:
>>
>>  Hi Harald,
>>
>> We have incorporated the changes on our GitHub repository 
>> (https://github.com/seitsu/registry-epp-maintenance/blob/master/draft-ietf-regext-epp-registry-maintenance.txt 
>> <https://github.com/seitsu/registry-epp-maintenance/blob/master/draft-ietf-regext-epp-registry-maintenance.txt>).
>>
>>>> To: [email-masked] <mailto:[email-masked]>
>>>> Cc: [email-masked] 
>>>> <mailto:[email-masked]>; 
>>>> [email-masked] <mailto:[email-masked]>; [email-masked] 
>>>> <mailto:[email-masked]>
>>>> Subject: Artart last call review of 
>>>> draft-ietf-regext-epp-registry-maintenance-17
>>>>
>>>> Caution: This email is from an external sender. Please do not click 
>>>> links or open attachments unless you recognize the sender and know 
>>>> the content is safe. Forward suspicious emails to isitbad@.
>>>>
>>>>
>>>>
>>>> There are a few things that need better definitions to be 
>>>> comprehensible enough for interoperable implementation. There is 
>>>> also one confusing formatting error that should be fixed before 
>>>> publication.
>>>>
>>>> Weak definitions:
>>>>
>>>> - "Maintenance event" is never defined. From context, it is 
>>>> possible to infer that a maintenance event refers to some service 
>>>> being partially or wholly unavailable in the time interval given; 
>>>> given that this is the whole point of the document, this should be 
>>>> explicit.
>>>>
>>>> <<
>>>> "Registries routinely update systems to ensure a higher quality of 
>>>> service, implement new services, or upgrade protocols to the newest 
>>>> standards.  These updates are pushed to various registry 
>>>> environments during time frames that are communicated to registrars 
>>>> as "maintenance events".  Registries usually inform registrars for 
>>>> maintenance events in various formats, none of which …..
>>>
>>> I'd add "This may require making services unavailable for some 
>>> limited time while the upgrade happens." Hitless upgrades are known 
>>> technology, but quite complex and not possible in all places - the 
>>> text proposed seems to assume that all updates require maintenance 
>>> events.
>>>
>>>> "
>>>> It should also be explicit that the service will be either fully 
>>>> and correctly available or not available at all, and that no harm 
>>>> (apart from being denied service) will come from trying to access 
>>>> the service in the maintenance interval; "maintenance" that, for 
>>>> instance, puts a test database up where the normal database is 
>>>> would be just a broken service, not "maintenance" in this sense. 
>>>> (If broken stuff might happen, I think you need a new impact value 
>>>> in addition to "full", "partial" or "none"
>>>> <<  In the case described above and any other similar maintenance 
>>>> events, the registry should not be allowing registrars to connect 
>>>> to the system by taking a "full" maintenance.  I don't believe we 
>>>> have ever experienced any maintenance event of the type described 
>>>> above.
>>>
>>>
>>>> - "maint:connection" and "maint:implementation" make very little 
>>>> sense as described. They may refer to having to reconnect the EPP 
>>>> service or to upgrade the EPP schema in use, but since the 
>>>> "maint:name" element of "maint:system"
>>>> seems to encompass WHOIS and others, the actions that may be 
>>>> required are not clear; an instruction to "do something 
>>>> connection-related" cannot be interoperably implemented. 
>>>> Suggestion: Either delete these elements or (if intended to be 
>>>> consumed by a human) add the option to add a text description of 
>>>> what should be done.
>>>>
>>>> <<  These flags are only meant to indicate that the registrar 
>>>> should review the maint:description element in the response for 
>>>> further details explaining actions the registrar will be effected 
>>>> by regarding the maintenance.  Adding a description to both of 
>>>> these elements seems to duplicate the information that should be in 
>>>> the maint:description element.  We would like to suggest this edit 
>>>> to the document:
>>>> From:
>>>> <maint:connection>
>>>> - pollType seems somewhat strange. The implicit definition seems to 
>>>> be that the client polls the server and the server replies with a 
>>>> list of outstanding maintenance events, with the value "create" 
>>>> returned the first time the server tells the client about the 
>>>> event. This implies that the server is required to keep state of 
>>>> what it has told each client about the event; same goes for event 
>>>> deletion. If such a state tracking requirement is indeed intended, 
>>>> this should be explicit.
>>>>
>>>> <<
>>>> This type of tracking requirement was not intended.  Registries 
>>>> will not be expected to keep state of what each registrar has 
>>>> received as far as the type of maintenance events.
>>>
>>> On reading RFC 5730, I see that the <poll> command has a queue of 
>>> events that can be retrieved, which will then constitute the memory 
>>> of what the client has received or not; if it's still in queue, it 
>>> hasn't been received. And for this scheme to work at all, there has 
>>> to be one distinct queue of notifications per client. In that 
>>> context, the "pollType" sounds much more reasonable.
>>>
>>>
>>>> In the list of elements in section 3, the indentation of 
>>>> <maint:environment> and the succeeding elements indicates that it 
>>>> is an element of <maint:systems>.
>>>> characters defined in ISO 8601 [RFC3339] MUST be used to represent 
>>>> date-time values." is not precise (I don't know if it's common) - 
>>>> it seems to claim that RFC 3339 is ISO 8601, which is just 
>>>> confusing. Suggested format: "The date-time format defined as 
>>>> "date-time" in [RFC3339], with time-offset="Z", MUST be used".
>>>>
>>>> <<
>>>> Text will be updated.
>>>> Styllistic issues:
>>>>
>>>> hurts the eyes :-) Unless there is tradition for this name, I'd 
>>>> suggest being boring and using "updateDate".
>>>>
>>>> <<
>>>> This document is following the same pattern used to signify the 
>>>> date the state of a domain was updated,  <domain:update> from RFC 
>>>> 5731, which we considered to be the standard to be followed.
>>>
>>>
>>> Ack! Tradition rules.
>>>
>>>> Having migration considerations before item descriptions looks a 
>>>> bit weird when reading the document top to bottom. Would it be 
>>>> nicer to move it after section 4?
>>>>
>>>> <<
>>>> The document is following the same format that is used in RFC 8807 
>>>> and RFC 8847 where migrations to the new version of the extension 
>>>> are covered immediately following the introduction.  However, we 
>>>> will update this document to move the migration section to after 
>>>> section 4 if this is what is needed.
>>>
>>>> I have not attempted to verify the schema, nor have I attempted to 
>>>> check the document against common styles for EPP extensions. If 
>>>> comments touch on things that are mandated by common EPP practices, 
>>>> feel free to consider these comments overridden.
>>>>
>>>> Hope this is helpful.
>>>>
>>>>
>>>>
>>>
>>> [email-masked] <mailto:[email-masked]>