jiebi/ids-paragraph-commentary-corpus huggingface dataset:
Draft: draft-ietf-webpush-protocol

Commentary: This is the initial update for the   review . I 'll wait to see if there are additional comments to address before merging . Editorial update to Section 7.4 Also fixed a the a nit . 
 Merging per  's response .
Paragraph (version A):
A 201 (Created) response indicates that the a push subscription was
created.  A URI for the push message subscription resource that was
created in response to the request MUST be returned in the Location
header field.
Paragraph (version B):
A 201 (Created) response indicates that the push subscription was
created.  A URI for the push message subscription resource that was
created in response to the request MUST be returned in the Location
header field.
Paragraph (version A):
A push service that does not support reliable delivery over
intermittent network connections or failing applications on devices,
forces the device to acknowledge receipt directly to the application
server, incurring additional power drain in order to establish
(usually secure) connections to the individual application servers.
Paragraph (version B):
A push service that does not support reliable delivery over
intermittent network connections or failing applications on devices,
forces the device to acknowledge receipt directly to the application
server, incurring additional power drain in order to establish and
maintain (usually secure) connections to the individual application
servers.
Draft: draft-ietf-webpush-protocol

Commentary:  commented in his review that the requirement for confidentiality seemed to be covered by TLS , unless the text was actually referring to e2e protections ( which I believe that it was ) . Moving the paragraph from the introduction of S8 to the immediate subsection resolves this confusion .
Paragraph (version A):
Applications using this protocol MUST use mechanisms that provide
confidentiality, integrity and data origin authentication.  The
application server sending the push message and the application on
the user agent that receives it are frequently just different
instances of the same application, so no standardized protocol is
needed to establish a proper security context.  The distribution of
subscription information from the user agent to its application
server also offers a convenient medium for key agreement.
Paragraph (version A):
For its requirements, the API has adopted I-D.ietf-webpush-encryption
to secure the content of messages from the push service.  Other
scenarios can be addressed by similar policies.
Paragraph (version B):
Applications using this protocol MUST use mechanisms that provide
end-to-end confidentiality, integrity and data origin authentication.
The application server sending the push message and the application
on the user agent that receives it are frequently just different
instances of the same application, so no standardized protocol is
needed to establish a proper security context.  The distribution of
subscription information from the user agent to its application
server also offers a convenient medium for key agreement.
Paragraph (version B):
For this requirement, the API has adopted I-D.ietf-webpush-encryption
to secure the content of messages from the push service.  Other
scenarios can be addressed by similar policies.
Draft: draft-ietf-webpush-protocol

Commentary: Caption the figure and use application server more consistently .
Paragraph (version A):
This protocol MUST use RFC2818 following the recommendations in
RFC7525.  This includes any communications between user agent and
push service, plus communications between the application and the
push service.  All URIs therefore use the "https" scheme.  This
provides confidentiality and integrity protection for subscriptions
and push messages from external parties.
Paragraph (version B):
This protocol MUST use RFC2818 following the recommendations in
RFC7525.  This includes any communications between user agent and
push service, plus communications between the application server and
the push service.  All URIs therefore use the "https" scheme.  This
provides confidentiality and integrity protection for subscriptions
and push messages from external parties.
Draft: draft-ietf-webpush-protocol

Commentary: Based on the IANA review : Update IANA Considerations to indicate the System Port 1001 is a suggestion Update inline references to 1001 to " TBD " 
 LGTM ( I 'll let you merge this one ) .
Paragraph (version A):
The push service MUST use HTTP over TLS [RFC2818] following the
recommendations in [RFC7525].  The push service shares the same
default port number (443/TCP) with HTTPS, but MAY also advertise the
IANA allocated TCP System Port 1001 using HTTP alternative services
RFC7838.
Paragraph (version B):
The push service MUST use HTTP over TLS [RFC2818] following the
recommendations in [RFC7525].  The push service shares the same
default port number (443/TCP) with HTTPS, but MAY also advertise the
IANA allocated TCP System Port (WEBPUSH-PORT) using HTTP alternative
services RFC7838.
Paragraph (version A):
Advertising the alternate port (1001) allows middleboxes to optimize
idle timeouts for connections specific to push scenarios with the
expectation that data exchange will be infrequent.
Paragraph (version B):
Advertising the alternate port (WEBPUSH-PORT) allows middleboxes to
optimize idle timeouts for connections specific to push scenarios
with the expectation that data exchange will be infrequent.
Paragraph (version A):
IANA is requested to assign the System Port number 1001 and the
service name "webpush" in accordance with RFC6335.
Paragraph (version B):
In accordance with RFC6335, it is requested that IANA assign the
suggested System Port number 1001 (or another port in the System
range) and the service name "webpush".
Draft: draft-ietf-webpush-protocol

Commentary: This draft attempts to address all of the issues identified during with the exception of Dealing with overload situations where further guidance has been requested from early implementers of webpush .
Paragraph (version A):
Examples in this document use the RFC7230.  Many of the exchanges can
be completed using HTTP/1.1.  Where HTTP/2 is necessary, the more
verbose frame format from RFC7540 is used.
Paragraph (version A):
The push service shares the same default port number (443/TCP) with
HTTPS, but MAY also advertise the IANA allocated TCP System Port 1001
using HTTP alternative services RFC7838.
Paragraph (version B):
The push service MUST use HTTP over TLS [RFC2818] following the
recommendations in [RFC7525].  The push service shares the same
default port number (443/TCP) with HTTPS, but MAY also advertise the
IANA allocated TCP System Port 1001 using HTTP alternative services
RFC7838.
Paragraph (version A):
To limit the number of stored push messages, the push service MAY
either expire messages prior to their advertised Time-To-Live or
reduce their advertised Time-To-Live.
Paragraph (version B):
To limit the number of stored push messages, the push service MAY
respond with a shorter Time-To-Live than proposed by the application
server in its request for push message delivery (ttl).  Once a
message has been accepted, the push service MAY later expire the
message prior to its advertised Time-To-Live.  If the application
server requested a delivery receipt, the push service MUST return a
failure response (acknowledge_message).
Draft: draft-ietf-webpush-protocol

Commentary: spelling corrections and updates to informative references ( works in progress )
Paragraph (version A):
However, reliability might not be necessary for messages that are
transient (e.g. an incoming call) or messages that are quickly
superseded (e.g. the current number of unread emails).
Paragraph (version B):
However, reliability might not be necessary for messages that are
transient (e.g. an incoming call) or messages that are quickly
superceded (e.g. the current number of unread emails).
Draft: draft-ietf-webpush-protocol

Commentary: " The ciphertext of the push message is included in the body of the request . " example looks like base64 - it should be clear it 's binary content ( ciphertext is not base64 ) we give an example with ciphertext , it should include the extra headers . Alternative is to say " The content of the push message is included " , and have a " I am walrus " example " - with a link to the encryption document for proper encrypted example . But since most implementations will require encryption - I think it 's better to add the extra headers and make it clear it 's binary . 
 I prefer the " Alternative " approach to keep the webpush examples simple and uncluttered . I will add a reference to the example in to illustrate encryption .
Paragraph (version B):
Examples do not include specific methods for push message encryption
or application server authentication because the protocol does not
define a mandatory system.  The examples in I-D.ietf-webpush-vapid
and I-D.ietf-webpush-encryption demonstrate the approach adopted by
the API for its requirements.
Paragraph (version A):
An application server requests the delivery of a push message by
sending a HTTP POST request to a push resource distributed to the
application server by a user agent.  The ciphertext of the push
message is included in the body of the request.
Paragraph (version B):
An application server requests the delivery of a push message by
sending a HTTP POST request to a push resource distributed to the
application server by a user agent.  The content of the push message
is included in the body of the request.
Draft: draft-ietf-webpush-protocol

Commentary: I ensured that the " proxy " text in UA and AS were similar . I removed the cross - references to and text in Section 7.5 , which is specific to PS policies if it does n't want to support multiple subscription sets . I did not call out potential UA scenarios in detail other than " monitoring on behalf " of other receivers or senders .  provides a mechanism to enable proxies - but it may be better to have separate drafts that describe specific policies that use this mechanism to support scenarios such as moving between UA(s ) . 
 and - please review and comment . 
 LGTM , but I 'll wait until others have commented before merging . 
 This works for me .
Paragraph (version A):
A user agent MAY omit the subscription set if it is unable to receive
push messages in an aggregated way for the lifetime of the
subscription.  This might be necessary if the user agent is
monitoring subscriptions for other clients (see sets-streams).
Paragraph (version B):
A user agent MAY omit the subscription set if it is unable to receive
push messages in an aggregated way for the lifetime of the
subscription.  This might be necessary if the user agent is
monitoring subscriptions on behalf of other push message receivers.
Paragraph (version A):
An application server MAY omit the receipt subscription if it is
unable to receive receipts in an aggregated way for the lifetime of
the receipt subscription.  This might be necessary if the application
server is monitoring receipt subscriptions on the behalf of other
push message senders (see sets-streams).
Paragraph (version B):
An application server MAY omit the receipt subscription if it is
unable to receive receipts in an aggregated way for the lifetime of
the receipt subscription.  This might be necessary if the application
server is monitoring receipt subscriptions on the behalf of other
push message senders.
Paragraph (version A):
A user agent that monitors subscriptions for other clients might
require multiple subscription sets.  Each subscription set can then
be managed independently, which might include being moved between
user agents.
Draft: draft-ietf-webpush-protocol

Commentary: Clean pull - request for replacing .
Paragraph (version A):
A user agent MAY omit the subscription set if it is unable to receive
push messages in an aggregated way for the lifetime of the
subscription.  This might be necessary if the user agent is
forwarding subscription requests from other clients.
Paragraph (version B):
A user agent MAY omit the subscription set if it is unable to receive
push messages in an aggregated way for the lifetime of the
subscription.  This might be necessary if the user agent is
monitoring subscriptions for other clients (see sets-streams).
Paragraph (version B):
An application server MAY omit the receipt subscription if it is
unable to receive receipts in an aggregated way for the lifetime of
the receipt subscription.  This might be necessary if the application
server is monitoring receipt subscriptions on the behalf of other
push message senders (see sets-streams).
Paragraph (version B):
A user agent that monitors subscriptions for other clients might
require multiple subscription sets.  Each subscription set can then
be managed independently, which might include being moved between
user agents.
Draft: draft-ietf-webpush-protocol

Commentary: suggested this . It 's a simplification that should reduce errors . It prevents topics like " Hello world ! " , but that 's probably a good thing on balance .
Paragraph (version A):
The grammar for the Topic header field uses the "token" and "quoted-
string" rules defined in RFC7230.
Paragraph (version A):
Any double quotes from the "quoted-string" form are removed before
comparing topics for equality.
Paragraph (version B):
The grammar for the Topic header field uses the "token" rule defined
in RFC7230.
Draft: draft-ietf-webpush-protocol

Commentary: Follow up to to ensure that the language is the same for both expiration sections .
Paragraph (version A):
A push service can remove a subscription at any time.  If a user
agent or application server has an outstanding request to a push
message subscription resource (monitor-subscription) or to a receipt
subscription resource (receive_receipt), this MUST be signaled by
returning a 404 (Not Found) status code.
Paragraph (version B):
A push service MAY expire a subscription at any time.  If there are
outstanding requests to a push message subscription resource
(monitor-subscription) from a user agent or to a receipt subscription
resource (receive_receipt) from an application server, this MUST be
signaled by returning a 404 (Not Found) status code.
Draft: draft-ietf-webpush-protocol

Commentary: Noticed while checking CI for other PRs .
Paragraph (version A):
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
document are to be interpreted as described in [RFC2119].
Paragraph (version B):
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
document are to be interpreted as described in RFC2119.
Draft: draft-ietf-webpush-protocol

Commentary: As suggested by 
 Thanks to all for the discussion , I was lazy and missed the MUST 404 on the section above . 
 The language for subscription and subscription sets is still a bit asymmetical . I 'll merge this PR and make the subsequent edits . For example can remove versus MAY expire ...
Paragraph (version A):
A push service MAY expire a subscription set at any time and MUST
also expire all push message subscriptions in the set.  If a user
agent has an outstanding request to a push subscription set (monitor-
set) this can be signaled by returning a 400-series status code, such
as 410 (Gone).
Paragraph (version B):
A push service MAY expire a subscription set at any time and MUST
also expire all push message subscriptions in the set.  If a user
agent has an outstanding request to a push subscription set (monitor-
set) this can be signaled by returning a 404 (Not Found) status code.
Draft: draft-ietf-webpush-protocol

Commentary: … nd UA use 
 You should get a cleaner diff if you merge .
Paragraph (version A):
An application server MAY include an Urgency header field in its
request for push message delivery.  This header field indicates the
message urgency.  The push service MUST not forward the Urgency
header field to the user agent.  A user agent MAY include the Urgency
header field when requesting push messages to indicate that it only
wants to receive messages at an equal or greater urgency.
Paragraph (version A):
An absent Urgency header field indicates that the request is to be
forwarded at "normal" urgency.  Multiple values for the header field
MUST NOT be included in requests; otherwise, the push service MUST
return a 400 (Bad Request) status code.
Paragraph (version B):
An application server MAY include an Urgency header field in its
request for push message delivery.  This header field indicates the
message urgency.  The push service MUST not forward the Urgency
header field to the user agent.  An push message without the Urgency
header field is forwarded as though it included a value of "normal".
Paragraph (version B):
A user agent MAY include the Urgency header field when monitoring for
push messages to indicate the lowest urgency of push messages that it
is willing to receive.  A push service MUST NOT deliver push messages
with lower urgency than the value indicated by the user agent in its
monitoring request.  Push messages of any urgency are delivered to a
user agent that does not include an Urgency header field when
monitoring for messages.
Paragraph (version B):
Multiple values for the Urgency header field MUST NOT be included in
requests; otherwise, the push service MUST return a 400 (Bad Request)
status code.
Draft: draft-ietf-webpush-protocol

Commentary: Should we include a reference to - perhaps in Acknowledgements ? 
 I do n't care about acknowledgments for -nice . But I do care about the issues that I raised on the list .
Paragraph (version B):
For a device that is battery-powered, it is often critical that it
remains dormant for extended periods.  Radio communication in
particular consumes significant power and limits the length of time
that the device can operate.
Paragraph (version B):
To avoid consuming resources to receive trivial messages, it is
helpful if an application server can communicate the urgency of a
message and if the user agent can request that the push server only
forward messages of a specific urgency.
Paragraph (version B):
An application server MAY include an Urgency header field in its
request for push message delivery.  This header field indicates the
message urgency.  The push service MUST not forward the Urgency
header field to the user agent.  A user agent MAY include the Urgency
header field when requesting push messages to indicate that it only
wants to receive messages at an equal or greater urgency.
Paragraph (version B):
An absent Urgency header field indicates that the request is to be
forwarded at "normal" urgency.  Multiple values for the header field
MUST NOT be included in requests; otherwise, the push service MUST
return a 400 (Bad Request) status code.
Draft: draft-ietf-webpush-protocol

Commentary: This replaces the PENDING section on correlation . I know that wanted to simply rely on ambient authority of some sort , but I think that this is the cleanest option . It does n't cost us anything significant either . 
 Does the PS return the push : set with each subscribe response or just the first one ? If returned in all cases , can the push : set change between responses ? If so , does the UA MUST use the latest one ? For a PS that wants to strongly require aggregation - besides using concurrent stream limits - can it return an error if the push : set is not included ? 
 Good questions , both of them , I 'll add a commit that answers them ( rather than answer them in these comments ) . 
 Answers provided ( more words ) ...
Paragraph (version B):
The aggregation of multiple subscriptions into a subscription set can
represent a significant efficiency improvement for a push service.
For that reason, if a subscription set is available, a user agent
MUST indicate an existing subscription set in a request to create a
subscription.  However, a user agent MAY omit the subscription set if
it is unable to receive push messages that are aggregated for the
lifetime of the subscription.  This might be necessary if the user
agent is forwarding requests from other clients.
Paragraph (version B):
The user agent adds a subscription set link relation to the request
to create a subscription.  This indicates which subscription set the
subscription is to be bound to.
Paragraph (version B):
This gives the push service the option to create a subscription
within an existing subscription set.  The push service returns the
same subscription set in the response, though it MAY use a new
subscription set if it is unable to reuse the provided one.
Paragraph (version B):
A push service MAY reject a request if it contains an unknown or
invalid subscription set, or a request that does not include a
subscription set.  An 429 status code can be used to indicate that
too many requests to create subscriptions sets were made.
Paragraph (version B):
How a push service detects that requests come from the same user
agent is implementation-dependent and could take ambient information
into consideration, such as the TLS connection, source IP address and
port.  Implementers are reminded that using some heuristics can
produce false positives and cause requests to be rejected
incorrectly.
Draft: draft-ietf-webpush-protocol

Commentary: Looks good aside from that one thing , the resolution of which I 'll leave to your discretion . 
 As discussed in cc
Paragraph (version A):
A push service MAY generate a 413 (Payload Too Large) status code in
response to requests that include an entity body that is too large.
Push services MUST NOT generate a 413 status code in responses to an
entity body that is 4k (4096 bytes) or less in size.
Paragraph (version B):
A push service MAY return a 429 (Too Many Requests) status code
RFC6585 when an application server has exceeded its rate limit for
push message delivery to a push resource.  The push service SHOULD
also include a Retry-After header RFC7231 to indicate how long the
application server is requested to wait before it makes another
request to the push resource.
Paragraph (version B):
A push service MAY return a 413 (Payload Too Large) status code
RFC7231 in response to requests that include an entity body that is
too large.  Push services MUST NOT return a 413 status code in
responses to an entity body that is 4k (4096 bytes) or less in size.