jiebi/ids-paragraph-commentary-corpus huggingface dataset:
Draft: draft-ietf-quic-transport

Commentary: These are all MUST in recovery and the editors discussed this and agreed that these should be MUST too .
Paragraph (version A):
Packet loss, in particular loss of a Handshake packet from the
server, can cause a situation in which the server cannot send when
the client has no data to send and the anti-amplification limit is
reached.  In order to avoid this causing a handshake deadlock,
clients SHOULD send a packet upon a probe timeout, as described in
QUIC-RECOVERY.  If the client has no data to retransmit and does not
have Handshake keys, it SHOULD send an Initial packet in a UDP
datagram of at least 1200 bytes.  If the client has Handshake keys,
it SHOULD send a Handshake packet.
Paragraph (version B):
Packet loss, in particular loss of a Handshake packet from the
server, can cause a situation in which the server cannot send when
the client has no data to send and the anti-amplification limit is
reached.  In order to avoid this causing a handshake deadlock,
clients MUST send a packet upon a probe timeout, as described in
QUIC-RECOVERY.  If the client has no data to retransmit and does not
have Handshake keys, it MUST send an Initial packet in a UDP datagram
of at least 1200 bytes.  If the client has Handshake keys, it SHOULD
send a Handshake packet.
Draft: draft-ietf-quic-http

Commentary: This text was pretty good and more or less covered the problem already , but I think that this might be slightly better . if you do n't like this , close this AND . 
 From a discussion on : We should probably have a conversation about the trade - offs with padding . Transport - layer padding is in some ways superior , like in how it can be granular to a single byte , which reserved streams and frames can not do . But PADDING frames at the transport are n't retransmitted when lost , which could lead to some interesting attacks if packets can be suppressed by an attacker . If retransmissions are n't padded , boom . Originally posted by in
Paragraph (version A):
Where HTTP/2 employs PADDING frames and Padding fields in other
frames to make a connection more resistant to traffic analysis,
HTTP/3 can either rely on transport-layer padding or employ the
reserved frame and stream types discussed in frame-reserved and
stream-grease.  These methods of padding produce different results in
terms of the granularity of padding, the effect of packet loss and
recovery, and how an implementation might control padding.
Paragraph (version B):
Where HTTP/2 employs PADDING frames and Padding fields in other
frames to make a connection more resistant to traffic analysis,
HTTP/3 can either rely on transport-layer padding or employ the
reserved frame and stream types discussed in frame-reserved and
stream-grease.  These methods of padding produce different results in
terms of the granularity of padding, how padding is arranged in
relation to the information that is being protected, whether padding
is applied in the case of packet loss, and how an implementation
might control padding.
Draft: draft-ietf-quic-recovery

Commentary: I 'm happy to merge this as is , but I 'll give it 24hrs in case others have comments . 
 This is weird in that it assumes some context that is n't provided : Perhaps instead : This " Because QUIC does not retransmit packets " thing is unnecessary . I 'll open a PR .
Paragraph (version A):
Recovery is a period of time beginning with detection of a lost
packet or an increase in the ECN-CE counter.  Because QUIC does not
retransmit packets, it defines the end of recovery as a packet sent
after the start of recovery being acknowledged.  This is slightly
different from TCP's definition of recovery, which ends when the lost
packet that started recovery is acknowledged.
Paragraph (version B):
A recovery period is entered when loss or ECN-CE marking of a packet
is detected.  A recovery period ends when a packet sent during the
recovery period is acknowledged.  This is slightly different from
TCP's definition of recovery, which ends when the lost packet that
started recovery is acknowledged.
Draft: draft-ietf-quic-transport

Commentary: Unlike the other transport parameter definitions , there is no type specified for the parameter . I will assume that the type is an integer ( like the other numeric - like transport parameters ) and submit a PR to adjust the wording so that it is in line with the other transport parameter descriptions , if that 's ok ? Thanks for all the great work that you are all doing on getting QUIC specified ! 
 Good catch ! Looks like all the other values have a type either implicitly or explicitly stated . is indeed intended to be an integer , a PR to that effect would be great . 
 Thanks
Paragraph (version A):
The maximum number of connection IDs from the peer that an
endpoint is willing to store.  This value includes the connection
ID received during the handshake, that received in the
preferred_address transport parameter, and those received in
NEW_CONNECTION_ID frames.  Unless a zero-length connection ID is
being used, the value of the active_connection_id_limit parameter
MUST be no less than 2.  If this transport parameter is absent, a
default of 2 is assumed.  When a zero-length connection ID is
being used, the active_connection_id_limit parameter MUST NOT be
sent.
Paragraph (version B):
The active connection ID limit is an integer value specifying the
maximum number of connection IDs from the peer that an endpoint is
willing to store.  This value includes the connection ID received
during the handshake, that received in the preferred_address
transport parameter, and those received in NEW_CONNECTION_ID
frames.  Unless a zero-length connection ID is being used, the
value of the active_connection_id_limit parameter MUST be no less
than 2.  If this transport parameter is absent, a default of 2 is
assumed.  When a zero-length connection ID is being used, the
active_connection_id_limit parameter MUST NOT be sent.
Draft: draft-ietf-quic-transport

Commentary: The description here was a little over enthusiastic : it only enters the " Send " state when something is sent . 
 From -transport section 3.1 : The event causing transition    is the host initially having data to send on the stream , which is not the case when the receiving part has just been created in its initial Recv state . I think the send stream should stay in Ready until it has data . This also aligns better with similar text in 3.2 . I suggest : p.s . see also , but which is more about being explicit about frames that cause stream creation ... rather than this issue , which is about the state the new sending part starts in . 
 This issue can be closed -- see commit above . 
 That commit has n't been merged , and is sitting in a branch that does n't appear to have an associated PR . 
 Oh -- sorry about that . I should have checked . 
 Wow , that sat there for ages . I made a PR .
Paragraph (version A):
The sending part of a bidirectional stream initiated by a peer (type
0 for a server, type 1 for a client) enters the "Ready" state then
immediately transitions to the "Send" state if the receiving part
enters the "Recv" state (stream-recv-states).
Paragraph (version B):
The sending part of a bidirectional stream initiated by a peer (type
0 for a server, type 1 for a client) starts in the "Ready" state when
the receiving part is created.
Draft: draft-ietf-quic-transport

Commentary: Fixes issue 
 Sect . 7 in transport refers to packer number spaces without any reference to what that might mean . These are only introduced later in sect . 12.3 . Also the text talks about crypto sequence numbers and the text is not very clear about these being different from packet numbers if you have n't been through TLS text . 
 This is still an issue . I think adding references to where packet number spaces are mentioned ( List of Common Terms and Section 7 ) would be sufficient . 
 Sounds great , would you be willing to write a PR 
 Fixed in .
Paragraph (version A):
A packet that does not increase the largest received packet number
for its packet number space by exactly one.  A packet can arrive
out of order if it is delayed or if earlier packets are lost or
delayed.
Paragraph (version B):
A packet that does not increase the largest received packet number
for its packet number space (packet-numbers) by exactly one.  A
packet can arrive out of order if it is delayed or if earlier
packets are lost or delayed.
Paragraph (version A):
The CRYPTO frame can be sent in different packet number spaces.  The
sequence numbers used by CRYPTO frames to ensure ordered delivery of
cryptographic handshake data start from zero in each packet number
space.
Paragraph (version B):
The CRYPTO frame can be sent in different packet number spaces
(packet-numbers).  The sequence numbers used by CRYPTO frames to
ensure ordered delivery of cryptographic handshake data start from
zero in each packet number space.
Draft: draft-ietf-quic-tls

Commentary: Can someone please verify my work ? I 've written two implementations here and the values match , but I value independent validation . 
 The value matches what quic - go is calculating . Will add this test vector as a unit test to my implementation . 
 Woo ! I 'm not as bad at this as I thought . Thanks 
 I can also confirm that it verifies in Wireshark . ( Likewise for the samples in Appendix A. ) 
 The Retry integrity check is different than the protection for other packets , so it would make sense to include an example in the document . We need code for it in addition to the sample so that it can be updated more readily . 
 I also tested these vectors and it works fine . Thanks !
Paragraph (version A):
test-vectors-initial contains test vectors for the initial packet
encryption.
Paragraph (version B):
test-vectors contains test vectors for packet encryption.
Draft: draft-ietf-quic-recovery

Commentary: I think this statement should be normative . Not sure if this is a design issue or not . 
 I 'm comfortable with this being editorial .
Paragraph (version A):
The probe timer is not set if the time threshold time-threshold loss
detection timer is set.  The time threshold loss detection timer is
expected to both expire earlier than the PTO and be less likely to
spuriously retransmit data.
Paragraph (version B):
The probe timer MUST NOT be set if the time threshold time-threshold
loss detection timer is set.  The time threshold loss detection timer
is expected to both expire earlier than the PTO and be less likely to
spuriously retransmit data.
Draft: draft-ietf-quic-recovery

Commentary: I proposed to remove this sentence here because all these values have actually been just defined in the previous sections . If a pointer to the appendix is desired , I think that should be mentioned earlier ( e.g. in the intro already ) that these lists existing in the appendix . 
 This seems fine to me , but I 'd like opinion as well .
Paragraph (version A):
kGranularity, smoothed_rtt, rttvar, and max_ack_delay are defined in
ld-consts-of-interest and ld-vars-of-interest.
Draft: draft-ietf-quic-recovery

Commentary: So here is an alternative proposal . However I also wonder why this paragraph is a MUST requirement while the previous statement ( avoiding multiple samples of the same packet ) is only a SHOULD ? I would see it rather the other way around or both MUSTs . 
 This is a great improvement , thanks . One additional suggestion ( for existing text ) below .
Paragraph (version A):
An RTT sample MUST NOT be generated on receiving an ACK frame that
does not newly acknowledge at least one ack-eliciting packet.  A peer
does not send an ACK frame on receiving only non-ack-eliciting
packets, so an ACK frame that is subsequently sent can include an
arbitrarily large Ack Delay field.  Ignoring such ACK frames avoids
complications in subsequent smoothed_rtt and rttvar computations.
Paragraph (version B):
An RTT sample MUST NOT be generated on receiving an ACK frame that
does not newly acknowledge at least one ack-eliciting packet.  A peer
usually does not send an ACK frame when only non-ack-eliciting
packets are received.  Therefore an ACK frame that contains
acknowledgements for only non-ack-eliciting packets could include an
arbitrarily large Ack Delay value.  Ignoring such ACK frames avoids
complications in subsequent smoothed_rtt and rttvar computations.
Draft: draft-ietf-quic-recovery

Commentary: ACK - only was only even used in the definition part and in - flight can also be defined using ack - eliciting . 
 I just realised that padding is the " complicating " thing here . I still do n't think we need to define " act - only " just for that but can rather be explicit about padding frames because otherwise this is easy to miss ( as I did initially ) . 
 While the defined term is not used elsewhere , the phrases " Packets containing only ACK frames " and " Packets only containing ACK frames " are used . We should either eliminate the definition or explicitly use the defined term in those places . 
 Of  's options , I think that this makes sense . Fewer defined terms means lower fixed cognitive load when reading this . Less jargon = good . I re - read the other spots mentioned and I believe the text is still correct , so I 'm going to accept this . Thanks for the simplification .
Paragraph (version A):
Any packet containing only one or more ACK frame(s).
Paragraph (version A):
Packets are considered in-flight when they have been sent and are
not ACK-only, and they are not acknowledged, declared lost, or
abandoned along with old keys.
Paragraph (version B):
Packets are considered in-flight when they are ack-eliciting or
contain a PADDING frame, and they have been sent but are not
acknowledged, declared lost, or abandoned along with old keys.
Draft: draft-ietf-quic-recovery

Commentary: Just a proposal but I would prefer to remove the advertising slang ( " decades of transport and security experience " and " makes it attractive " ) . 
 Is n't the introduction the right place for ad copy , though ? It describes what the document hopes to achieve and why it 's worth doing . I think some of the rewording you 've done here is an improvement , but I 'm not convinced we should edit out the fact that we 're trying to incorporate many years of work that has n't been universally deployable . 
 I 'm fine with this new language .
Paragraph (version A):
QUIC is a new multiplexed and secure transport atop UDP.  QUIC builds
on decades of transport and security experience, and implements
mechanisms that make it attractive as a modern general-purpose
transport.  The QUIC protocol is described in QUIC-TRANSPORT.
Paragraph (version A):
QUIC implements the spirit of existing TCP congestion control and
loss recovery mechanisms, described in RFCs, various Internet-drafts,
and also those prevalent in the Linux TCP implementation.  This
document describes QUIC congestion control and loss recovery, and
where applicable, attributes the TCP equivalent in RFCs, Internet-
drafts, academic papers, and/or TCP implementations.
Paragraph (version B):
QUIC is a new multiplexed and secure transport protocol atop UDP,
specified in QUIC-TRANSPORT.  This document describes congestion
control and loss recovery for QUIC.  Mechanisms described in this
document follow the spirit of existing TCP congestion control and
loss recovery mechanisms, described in RFCs, various Internet-drafts,
or academic papers, and also those prevalent in TCP implementations.
Draft: draft-ietf-quic-transport

Commentary: Fixes issue . 
 The wording " between when ... and when ... " or " between when ... and ... " is odd . There are two instances of this in . 
 Fixed by . 
 Not critical , perhaps , but I agree that this is less awkward .
Paragraph (version A):
Unlike the token that is created for a Retry packet, there might be
some time between when the token is created and when the token is
subsequently used.  Thus, a token SHOULD have an expiration time,
which could be either an explicit expiration time or an issued
timestamp that can be used to dynamically calculate the expiration
time.  A server can store the expiration time or include it in an
encrypted form in the token.
Paragraph (version B):
Unlike the token that is created for a Retry packet, which is used
immediately, the token sent in the NEW_TOKEN frame might be used
after some period of time has passed.  Thus, a token SHOULD have an
expiration time, which could be either an explicit expiration time or
an issued timestamp that can be used to dynamically calculate the
expiration time.  A server can store the expiration time or include
it in an encrypted form in the token.
Paragraph (version A):
An endpoint measures the delays intentionally introduced between when
the packet with the largest packet number is received and an
acknowledgment is sent.  The endpoint encodes this delay in the Ack
Delay field of an ACK frame (see frame-ack).  This allows the
receiver of the ACK to adjust for any intentional delays, which is
important for getting a better estimate of the path RTT when
acknowledgments are delayed.  A packet might be held in the OS kernel
or elsewhere on the host before being processed.  An endpoint MUST
NOT include delays that it does not control when populating the Ack
Delay field in an ACK frame.
Paragraph (version B):
An endpoint measures the delays intentionally introduced between the
time the packet with the largest packet number is received and the
time an acknowledgment is sent.  The endpoint encodes this delay in
the Ack Delay field of an ACK frame (see frame-ack).  This allows the
receiver of the ACK to adjust for any intentional delays, which is
important for getting a better estimate of the path RTT when
acknowledgments are delayed.  A packet might be held in the OS kernel
or elsewhere on the host before being processed.  An endpoint MUST
NOT include delays that it does not control when populating the Ack
Delay field in an ACK frame.
Draft: draft-ietf-quic-transport

Commentary: Is " AEAD " a thing , or a descriptor ? I read the original as " an AEAD [ algorithm ] " , but this change seems to consider AEAD as a technique which can be applied . 
 I modeled this on the previous sentence that says ( italics ): Note the absence of " an " in front of the italicized text . The " AEAD " in the second sentence is simply another way to write " authenticated encryption with additional data . "
Paragraph (version A):
All QUIC packets except Version Negotiation packets use authenticated
encryption with additional data (AEAD) RFC5116 to provide
confidentiality and integrity protection.  Retry packets use an AEAD
to provide integrity protection.  Details of packet protection are
found in QUIC-TLS; this section includes an overview of the process.
Paragraph (version B):
All QUIC packets except Version Negotiation packets use authenticated
encryption with additional data (AEAD) RFC5116 to provide
confidentiality and integrity protection.  Retry packets use AEAD to
provide integrity protection.  Details of packet protection are found
in QUIC-TLS; this section includes an overview of the process.
Draft: draft-ietf-quic-transport

Commentary: Now I 'm worried about the interdependency between these documents ...
Paragraph (version A):
Section 6.4 of DPLPMTUD provides considerations for implementing
Datagram Packetization Layer PMTUD (DPLPMTUD) with QUIC.
Paragraph (version A):
When implementing the algorithm in Section 5.3 of DPLPMTUD, the
initial value of BASE_PMTU SHOULD be consistent with the minimum QUIC
packet size (1232 bytes for IPv6 and 1252 bytes for IPv4).
Paragraph (version B):
Section 6.3 of DPLPMTUD provides considerations for implementing
Datagram Packetization Layer PMTUD (DPLPMTUD) with QUIC.
Paragraph (version B):
When implementing the algorithm in Section 5 of DPLPMTUD, the initial
value of BASE_PMTU SHOULD be consistent with the minimum QUIC packet
size (1232 bytes for IPv6 and 1252 bytes for IPv4).
Draft: draft-ietf-quic-recovery

Commentary: From recovery to transport . 
 currently states : notes that nowhere do we define precisely how a receiver might do this detection . Specifically a receiver could implement this as when a newly received packet is smaller than the largest acked , or as when the packet is larger than largest acked plus one . Doing the former would actually not help with loss detection , since the receiver would not ack immediately on a gap . We should add some text codifying the latter . 
 That section used to be in recovery , where we have a definition  is now unused ) , so I 'd suggest we move it over . " Out - of - order Packets : : Packets that do not increase the largest received packet number for its packet number space by exactly one . Packets arrive out of order when earlier packets are lost or delayed . " 
 Is n't this supposed to be " Packets that increase the largest received packet number ... by more than one . " in this case ? 
 Thinking about this some more , there are three possible definitions here for out - of - order : newly received packet is greater than largest received by more than one , newly received packet is smaller than the largest received , ( 1 ) and ( 2 ) . ( 1 ) is the obvious case where a loss happens and a subsequent packet is received . ( 2 ) is the reordering case , where an earlier packet is delivered later , and while it does not indicate loss , it does indicate that a gap was filled . It 's useful to signal ( 2 ) as well immediately to prevent a sender from unnecessarily retransmitting what it believes to be a missing packet . The definition we want for " out - of - order " is the one that is most useful for determining when to send an immediate ack . The definition in the PR captures both ( 1 ) and ( 2 ) , and is probably the one we want . 
 : If you believe we ought to change the definition , please re - open , and we can continue this discussion . 
 Thank you for working on this .
Paragraph (version A):
Packets that do not increase the largest received packet number
for its packet number space by exactly one.  Packets arrive out of
order when earlier packets are lost or delayed.
Paragraph (version B):
A packet that does not increase the largest received packet number
for its packet number space by exactly one.  A packet can arrive
out of order if it is delayed or if earlier packets are lost or
delayed.