jiebi/TextFlow huggingface dataset:
Original text:
This document is meant as a supplement to existing Working Group practices.  It provides guidance to Working Group chairs and participants on how they can best use GitHub within the framework <del> established by RFC 2418 RFC2418.  The small number of rules in this document are there to ensure common usage patterns between Working Groups and to avoid issues that have been encountered in the past. </del>  A companion document, GH-CONFIG, describes administrative processes that support the practices described in this document. For both sets of users, this document aims to provide some amount of advice on practices that have proven to be effective.  1.5. The words "MUST", "MUST NOT", "SHOULD", "SHOULD NOT", and "MAY" are

Reviewer comments:
For , but not all of it.
Some working groups use GitHub to manage changes to charters or other working group materials, like agendas and presentations for sessions. I'd suggest that no great amount of detail is needed because these aren't the primary focus of the document, but it probably should include at least a passing mention of these uses and acknowledge that they are permitted.
Discussed in Singapore; MT to add text.
Closed in .
How this fits into existing processes is something that needs more thorough investigation if we're publishing an RFC on this.
Discussed in Singapore; no objections, merged, and closing.

Revised text:
This document is meant as a supplement to existing Working Group practices.  It provides guidance to Working Group chairs and participants on how they can best use GitHub within the framework  <ins> established by RFC 2418 RFC2418.  This document aims to establish norms that reduce the variation in usage patterns between different Working Groups and to avoid issues that have been encountered in the past. </ins> A companion document, GH-CONFIG, describes administrative processes that support the practices described in this document. For both sets of users, this document aims to provide some amount of advice on practices that have proven to be effective. <ins> This document only aims to address use of GitHub in developing documents.  Working Groups could choose to use the tool to aid in managing their charter or session materials such as agendas, minutes, and presentations.  Though the advice here might apply more broadly, using GitHub to manage other material is out of scope for this document. </ins> 1.5. The words "MUST", "MUST NOT", "SHOULD", "SHOULD NOT", and "MAY" are
Original text:
GitHub prominently links to the CONTRIBUTING file on certain pages. This file SHOULD be used in preference to the README for information <del> that new contributors need.  A link to the CONTRIBUTING file from the README is advised. </del>  In addition to Working Group policies, notices on repositories MUST <del> include citations for BCPs 78 and 79 (COPYRIGHT, IPR) and other IETF contribution policies.  A copy or reference to the IETF Note Well [6] is ideal. </del>  3. A document editor can still use GitHub independently for documents that they edit, even if the Working Group does not expressly choose <del> to use GitHub.  Any such public repository MUST follow the guidelines in BCPs 78 and 79 (COPYRIGHT, IPR) and bear notices to that effect. This recognizes that editors have traditionally chosen their own methods for managing the documents they edit but preserves the need for contributors to understand their obligations with respect to IETF processes. </del>  3.2.

Reviewer comments:
This consolidates text about notices in the "communicating policies" section, which seems most appropriate.
Thanks!

Revised text:
GitHub prominently links to the CONTRIBUTING file on certain pages. This file SHOULD be used in preference to the README for information  <ins> that new contributors need.  The README SHOULD contain a link to the CONTRIBUTING file. </ins> In addition to Working Group policies, notices on repositories MUST  <ins> include citations for the IETF Note Well [6]. </ins> 3. A document editor can still use GitHub independently for documents that they edit, even if the Working Group does not expressly choose  <ins> to use GitHub.  Any such public repository MUST follow the IETF Note Well and bear notices; see notices.  This recognizes that editors have traditionally chosen their own methods for managing the documents they edit but preserves the need for contributors to understand their obligations with respect to IETF processes. </ins> 3.2.
Original text:
Version compatibility is not symmetric: it is possible for version A to be compatible with version B and for B not to be compatible with A.  This could happen for example if version B is a strict superset <del> of version A. </del>  Note that version compatibility does not mean that every single possible instance of a first flight will succeed in conversion to the

Reviewer comments:
LGTM.
This is a very important section, but I found it to be a little muddy. In particular, the directionality of the phrase A is compatible with B was unclear. An example would help here, I think.

Revised text:
Version compatibility is not symmetric: it is possible for version A to be compatible with version B and for B not to be compatible with A.  This could happen for example if version B is a strict superset  <ins> of version A: if version A includes the concept of streams and STREAM frames, and version B includes the concepts of streams and tubes along with STREAM and TUBE frames, then A would be compatible with B but B would not be compatible with A. </ins> Note that version compatibility does not mean that every single possible instance of a first flight will succeed in conversion to the
Original text:
2.5. <del> The client's first connection attempt SHOULD be made using the version that the server is most likely to support.  The client selects the version most likely to be supported from the versions that are compatible with the client's most preferred version. Without additional information this could mean selecting the oldest </del>  version that the client supports. 3.

Reviewer comments:
Section 2.5 says unconditionally that the client chooses the most compatible version. This isn't right, because the most compatible version isn't what it is looking to end up on. What the client should choose is probably the most compatible version of those that are compatible (directionality ?) with its most preferred version.
Rereading this, I think the directionality is correct in the existing text. But perhaps we could figure out better wording.
LGTM with the following edits.

Revised text:
2.5.  <ins> When the client picks its original version, it will try to avoid incompatible version negotiation to save a round trip.  Therefore, the client SHOULD pick an original version to maximize the combined probability that both: The server knows how to parse first flights from the original version. The original version is compatible with the client's preferred version. Without additional information, this could mean selecting the oldest </ins> version that the client supports. 3.
Original text:
defined in QUIC) in Supported Version fields. Clients will ignore a Version Negotiation packet if it contains the <del> original version attempted by the client.  The client also ignores a Version Negotiation packet that contains incorrect connection ID fields; see QUIC-INVARIANTS. </del>  Upon receiving the Version Negotiation packet, the client will search for a version it supports in the list provided by the server.  If it

Reviewer comments:
URL here, it feel lacking normative language. The current text gives feel like there are other options the client can do and these are examples. if that is true what are those other options? if the client behave differently than described here as there is no normative language will that not cause interoperability issues?
The normative language already exists in . That said, the QUIC-VN draft is written in terms of QUIC invariants so we should tweak this.
we should or we should not?
We should
takes care of this

Revised text:
defined in QUIC) in Supported Version fields. Clients will ignore a Version Negotiation packet if it contains the  <ins> original version attempted by the client; see downgrade.  The client also ignores a Version Negotiation packet that contains incorrect connection ID fields; see QUIC-INVARIANTS. </ins> Upon receiving the Version Negotiation packet, the client will search for a version it supports in the list provided by the server.  If it
Original text:
Version Negotiation packet to indicate that the version the client chose is unacceptable, but doesn't allow the client to safely make use of that information to create a new connection with a mutually <del> supported version. </del>  With proper safety mechanisms in place, the Version Negotiation packet can be part of a mechanism to allow two QUIC implementations

Reviewer comments:
Add a short text in the introduction section to define how this document updates RFC 8999.
Thanks for taking the time, Christian! I appreciate it.
We have agreed to mark this document as updating RFC 8999. Fine, but this lacks a bit of discipline. We should have a statement inside the text (not just the abstract) explaining in which way RFC 8999 is updated.
Can someone propose text here? Based on our discussion in , there is no agreement inside the IETF on what "updates" means so I'm not sure what text would be helpful for readers.
NAME see PR

Revised text:
Version Negotiation packet to indicate that the version the client chose is unacceptable, but doesn't allow the client to safely make use of that information to create a new connection with a mutually  <ins> supported version.  This document updates QUIC-INVARIANTS by defining version negotiation mechanisms that leverage the Version Negotiation packet. </ins> With proper safety mechanisms in place, the Version Negotiation packet can be part of a mechanism to allow two QUIC implementations
Original text:
QUIC connections are shared state between a client and a server INV. The compatible version negotiation mechanism defined in this document <del> (see compat-vn) operates inside of a QUIC connection; i.e., the packets with the original version are part of the same connection as the packets with the negotiated version.  On the other hand, the incompatible version negotiation mechanism, which leverages QUIC Version Negotiation packets (see incompat-vn) conceptually operates across two QUIC connections: one before the Version Negotiation packet, and a distinct connection after. </del>  4.2.

Reviewer comments:
No real complaint with what existed before, but I thought that this might be clearer.
Approved with one nit

Revised text:
QUIC connections are shared state between a client and a server INV. The compatible version negotiation mechanism defined in this document  <ins> (see compat-vn) is performed as part of a single QUIC connection; that is, the packets with the original version are part of the same connection as the packets with the negotiated version. In comparison, the incompatible version negotiation mechanism, which leverages QUIC Version Negotiation packets (see incompat-vn) conceptually operates across two QUIC connections: the connection attempt prior to receiving the Version Negotiation packet is distinct from the connection with the incompatible version that follows. </ins> 4.2.
Original text:
Clients MAY include versions following the pattern "0x?a?a?a?a" in their "Compatible Version" list, and the server in their "Supported Version" list.  Those versions are reserved to exercise version <del> negotiation (see the Versions section of QUIC), and MUST be ignored </del>  when parsing these fields.  On the other hand, the "Received Negotiation Version" list MUST be identical to the received Version Negotiation packet, so clients MUST NOT add or remove reserved

Reviewer comments:
This construction directly undermines greasing by privileging the handling of greased versions. Please don't do this. As I alluded to in , this doesn't need to match the Version Negotiation packet/datagram contents. What is important here is that the list doesn't include a version that the client would have preferred to attempt over the current one. If you validate the server values that way, then you never have to worry about greased versions being different in the two different places. Indeed, you can have the server offer Version Negotiation packets that include more versions than they claim in their handshake (this being beneficial during the rollout of a fancy new version of the protocol).
Can you elaborate on how this undermines greasing? All we say is that you can add grease to version lists, but the Received Negotiation Version list needs to be transmitted as an opaque blob. We don't treat greased versions differently on receipt anywhere.
Well, the second MUST NOT pertains to something that I think should be removed. But you say "[reserved versions] MUST be ignored when parsing these fields". That tells implementations to train themselves to recognize greased versions. At that point, they are no longer treating these as versions that they just don't understand, but something special. The whole point of using an odd pattern was to ensure that this never happened.
Fair enough, if we replaced with: Would that be OK?
That's all I'm asking for. (Along with striking the echo of the VN packet, but we'll pursue that separately. The requirement there is reasonable if you assume that echoing the bits is necessary.)

Revised text:
Clients MAY include versions following the pattern "0x?a?a?a?a" in their "Compatible Version" list, and the server in their "Supported Version" list.  Those versions are reserved to exercise version  <ins> negotiation (see the Versions section of QUIC), and will be ignored </ins> when parsing these fields.  On the other hand, the "Received Negotiation Version" list MUST be identical to the received Version Negotiation packet, so clients MUST NOT add or remove reserved
Original text:
Version Negotiation packets on that connection. Both endpoints MUST parse their peer's Version Information during the <del> handshake.  If the Version Information was missing or if parsing it failed (for example, if it is too short or if its length is not divisible by four), then the endpoint MUST close the connection; if the connection was using QUIC version 1, that connection closure MUST use a transport error of type "TRANSPORT_PARAMETER_ERROR". </del>  If a client has reacted to a Version Negotiation packet, it MUST validate that the server's "Other Versions" field does not contain

Reviewer comments:
Section 5 describes Version Downgrade Prevention. If a client receives a VN packet and selects a new attempted version, it will format the "compatible VN" extension and document in it the previously attempted version and the VN parameters. The server who understands the extension will then verify that the VN was not a downgrade attack. This supposes that the server supports the extension. If it does not, the server will ignore the parameter, and will not verify anything. It also will not include that parameter in its parameter set. What should the client do in that scenario? Should it just close the connection with versionnegotiation error?

Revised text:
Version Negotiation packets on that connection. Both endpoints MUST parse their peer's Version Information during the  <ins> handshake.  If parsing the Version Information failed (for example, if it is too short or if its length is not divisible by four), then the endpoint MUST close the connection; if the connection was using QUIC version 1, that connection closure MUST use a transport error of type "TRANSPORT_PARAMETER_ERROR". If the Version Information was missing, the endpoints MAY complete the handshake if they have reason to believe the peer might not support this extension.  However, if a client has reacted to a Version Negotiation packet and the Version Information was missing, the client MUST close the connection; if the connection was using QUIC version 1, that connection closure MUST use a transport error of type "VERSION_NEGOTIATION_ERROR". </ins> If a client has reacted to a Version Negotiation packet, it MUST validate that the server's "Other Versions" field does not contain
Original text:
VN packet to indicate that the version the client offered is unacceptable, but doesn't allow the client to safely make use of that information to create a new connection with a mutually supported <del> version.  With proper safety mechanisms in place, the VN packet can be part of a mechanism to allow two QUIC implementations to negotiate between two totally disjoint versions of QUIC, at the cost of an extra round trip.  However, it is beneficial to avoid that cost whenever possible, especially given that most incremental versions are broadly similar to the the previous version. This specification describes a simple version negotiation mechanism which optionally leverages similarities between versions and can negotiate between the set of "compatible" versions in a single round trip. </del>  1.1.

Reviewer comments:
The "single round trip" thing isn't really a guarantee given various factors. Setting this up as additional round trips is cleaner and more accurate. I adjusted the paragraph structure to match.
The introduction reads like the draft only defines compatible version negotiation. It probably needs to be written to be more general.
Fair enough.
Thanks, that is a lot clearer

Revised text:
VN packet to indicate that the version the client offered is unacceptable, but doesn't allow the client to safely make use of that information to create a new connection with a mutually supported  <ins> version. With proper safety mechanisms in place, the VN packet can be part of a mechanism to allow two QUIC implementations to negotiate between two totally disjoint versions of QUIC.  This document specifies version negotiation using VN packets, which adds an extra round trip to connection establishment if needed. It is beneficial to avoid additional round trips whenever possible, especially given that most incremental versions are broadly similar to the the previous version.  This specification also defines a simple version negotiation mechanism which leverages similarities between versions and can negotiate between the set of "compatible" versions without additional round trips. </ins> 1.1.
Original text:
7. <del> The client's first flight SHOULD be sent using the version that the server is most likely to support (in the absence of other information, this will often be the oldest version the client supports). </del>  8.

Reviewer comments:
Though it might be the oldest version that is compatible with the most-preferred version, it isn't just "oldest".

Revised text:
7.  <ins> The client's first connection attempt SHOULD be made using the version that the server is most likely to support.  The client selects the version it believes to be best supported from the versions that are compatible with the client's most preferred version.  Without additional information this could mean selecting the oldest version that the client supports. </ins> 8.
Original text:
8. <del> QUIC version 1 features retry packets, which the server can send to </del>  validate the client's IP address before parsing the client's first <del> flight.  This impacts compatible version negotiation because a server who wishes to send a retry packet before parsing the client's first flight won't have parsed the client's Version Information yet.  If a future document wishes to define compatibility between two versions that support retry, that document MUST specify how version </del>  negotiation (both compatible and incompatible) interacts with retry during a handshake that requires both.  For example, that could be <del> accomplished by having the server send a retry packet first and validating the client's IP address before starting version negotiation and deciding whether to use compatible version negotiation on that connection (in that scenario the retry packet would be sent using the original version). </del>  9.

Reviewer comments:
Retry packets have a capital R protocols aren't "who" paragraphs are good minor edits for brevity

Revised text:
8.  <ins> QUIC version 1 features Retry packets, which the server can send to </ins> validate the client's IP address before parsing the client's first  <ins> flight.  A server that sends a Retry packet can do so before parsing the client's first flight.  A server that sends a Retry packet therefore might not have processed the client's Version Information before doing so. If a future document wishes to define compatibility between two versions that support retry, that document MUST specify how version </ins> negotiation (both compatible and incompatible) interacts with retry during a handshake that requires both.  For example, that could be  <ins> accomplished by having the server send a Retry packet first and validating the client's IP address before attempting compatible version negotiation.  In that scenario the Retry packet would be sent using the original version. </ins> 9.
Original text:
version_information <del> permanent (if this document is approved) </del>  This document  12.2. This document registers a new value in the QUIC Transport Error Codes Error negotiating version <del> permanent (if this document is approved) </del>  This document 

Reviewer comments:
I just saw a provisional registration for the 0xff73db value (from the current draft). This contains a note suggesting that the value might become permanent. Given how crucial version negotiation could be, I think we should seriously consider taking a codepoint from the 0-63 range.
Agreed, that was the intent but it wasn't clear from the draft. I wrote in to make it clearer.

Revised text:
version_information  <ins> provisional </ins> This document <ins> When this document is approved, it will request permanent allocation of a codepoint in the 0-63 range to replace the provisional codepoint described above. </ins> 12.2. This document registers a new value in the QUIC Transport Error Codes Error negotiating version  <ins> provisional </ins> This document <ins> When this document is approved, it will request permanent allocation of a codepoint in the 0-63 range to replace the provisional codepoint described above. </ins>