Re: [w3c/payment-request] Editorial Fit & Finish Changes (#838)

> 1) There is no mention to the payment handler spec even though handlers are mentioned several times. Should there be a mention in the dependencies or refs section?

Our intention was not to make it a dependency, as, for instance, Safari and Firefox don't implement the payment handlers API. If the changes in the future, then yeah :)  

> 2) Why is there both a dependencies and refs section, don't they signify the same thing, especially given the breakdown to normative and informative in the refs section.

The dependencies section is basically an somewhat redundant editorial tool that helps us with spec writing. Eventually, we want the dependencies section to be automatically generated (i.e., have a section "Terms cited by reference".... but ReSpec can't do that yet. Hopefully later in the year.) 

However, I can't get rid of it because it would break a bunch of things :( 

> 3) This is more of an architectural comment, but having the PaymentResponse not be an immutable object (with respect to the retry operation) seems like something we may want to reconsider in favor of immutability and an explicit return value for retry (if we haven't already).

That one is complicated, but yeah... the problem is that it has its own state machine inside that controls various things. It's as immutable as it can be, given the constraints that we have... ideally, we should have never had PaymentResponse... I think Apple's Session model was a better solution... water... bridge... personal opinions. 

But seriously, unless it's going to impede certain kinds of interactions, I'd be inclined to just live with it. It's "good enough"™️

> 4) The first paragraph after the NOTE block in section 3 (19th page) is incredibly hard to read. I don't have much context on the concept it is describing, so I didn't feel confident I could write an accurate and cleaner sentence.

Let's do that in a new bug. 

> 5) The description of "error" in 6.3 is not very clear. Is it accurate to describe this as a global error message or a fallback error message when a more specific error field is not appropriate?

As above. Let's do that in a new bug. 

> 6) Section 11.4 pulls the term redactList out of nowhere, with no context. Is it fair to say that this is a user agent constructed list of field thought to provide security benefits if redacted?

Privacy, but you are correct. Could probably be better introduced.  

7) It looks funky that the Assert statements in algorithm sections get their own highlighting box when no other standard term does, is that avoidable?

It is, but it's convention from other specs... so we are just cargo cutting. We make them stand out because `assert:` literally means crash the browser. We don't ever want to hit those, so we want browser implementers to be sanity checking what we wrote via those asserts. 


-- 
You are receiving this because you are subscribed to this thread.
Reply to this email directly or view it on GitHub:
https://github.com/w3c/payment-request/pull/838#issuecomment-468290336