jiebi/ids-paragraph-commentary-corpus huggingface dataset:
Draft: draft-ietf-rtcweb-jsep

Commentary: Not sure this is correct yet . Have a read of text in bugs . 
 The fourth sentence of the second bullet of section 5.2.1 is confusing . ( It starts " It is RECOMMENDED that the < sess - id " . ) RFC3265 requires the initial sess - id high - order bit to be zero . As written , this can be read to say that setting that bit to zero is only RECOMMENDED , and that it 's possible to have sess - ids that are something other than 64 bits . You mean to say " Do what 3265 says to do and make the lower 63 bits random " . Here 's one possible replacement for the sentence : " RFC 3265 requires that the high - order bit of the initial < sess - idbe zero . It is RECOMMENDED that the remaining 63 bits be initially set to a cryptographically random value . " 
 Yes , this is a reasonable change . 
 The text from 3264 is The numeric value of the session i d and version in the o line MUST be representable with a 64 bit signed integer . The initial value of the version MUST be less than ( 262)-1 , to avoid rollovers . My read of this is the two high order bits need to be zero 
 Is there some other SDP formatting that requires this number to be positive ? 
 LGTM
Paragraph (version A):
The second SDP line MUST be an "o=" line, as specified in RFC4566,
Section 5.2.  The value of the <username> field SHOULD be "-".
RFC3264 requires that the <sess-id> be representable as a 64-bit
signed integer.  It is RECOMMENDED that the <sess-id> be generated
as a 64-bit quantity with the high bit being sent to zero and the
remaining 63 bits being cryptographically random.  The value of
the <nettype> <addrtype> <unicast-address> tuple SHOULD be set to
a non-meaningful address, such as IN IP4 0.0.0.0, to prevent
leaking the local address in this field.  As mentioned in RFC4566,
the entire o= line needs to be unique, but selecting a random
number for <sess-id> is sufficient to accomplish this.
Paragraph (version B):
The second SDP line MUST be an "o=" line, as specified in RFC4566,
Section 5.2.  The value of the <username> field SHOULD be "-".
The sess-id MUST be representable by a 64-bit signed integer, and
the initial value MUST be less than (2**62)-1, as required by
RFC3264.  It is RECOMMENDED that the sess-id be constructed by
generating a 64-bit quantity with the two highest bits being set
to zero and the remaining 62 bits being cryptographically random.
The value of the <nettype> <addrtype> <unicast-address> tuple
SHOULD be set to a non-meaningful address, such as IN IP4 0.0.0.0,
to prevent leaking the local address in this field.  As mentioned
in RFC4566, the entire o= line needs to be unique, but selecting a
random number for <sess-id> is sufficient to accomplish this.
Draft: draft-ietf-rtcweb-jsep

Commentary: Section 1.2 second paragraph - " This was rejected based on a feeling " . Can you write something that speaks to consensus here ? " Based on a feeling " is n't quite right . Maybe " using the argument " ? 
 Sure . 
 LGTM
Paragraph (version A):
A second approach that was considered but not chosen was to decouple
the management of the media control objects from session
descriptions, instead offering APIs that would control each component
directly.  This was rejected based on a feeling that requiring
exposure of this level of complexity to the application programmer
would not be beneficial; it would result in an API where even a
simple example would require a significant amount of code to
orchestrate all the needed interactions, as well as creating a large
API surface that needed to be agreed upon and documented.  In
addition, these API points could be called in any order, resulting in
a more complex set of interactions with the media subsystem than the
JSEP approach, which specifies how session descriptions are to be
evaluated and applied.
Paragraph (version B):
A second approach that was considered but not chosen was to decouple
the management of the media control objects from session
descriptions, instead offering APIs that would control each component
directly.  This was rejected based on the argument that requiring
exposure of this level of complexity to the application programmer
would not be beneficial; it would result in an API where even a
simple example would require a significant amount of code to
orchestrate all the needed interactions, as well as creating a large
API surface that needed to be agreed upon and documented.  In
addition, these API points could be called in any order, resulting in
a more complex set of interactions with the media subsystem than the
JSEP approach, which specifies how session descriptions are to be
evaluated and applied.
Draft: draft-ietf-rtcweb-jsep

Commentary: There are two paragraphs on page 50 that start " The next step is to " . They are both referring to the same step . I suggest combining the paragraphs . 
 I think I would just change the second one to " Finally " 
 LGTM
Paragraph (version A):
The next step is to generate m= sections for each m= section that is
present in the remote offer, as specified in RFC3264, Section 6.  For
the purposes of this discussion, any session-level attributes in the
offer that are also valid as media-level attributes are considered to
be present in each m= section.
Paragraph (version A):
The next step is to go through each offered m= section.  Each offered
m= section will have an associated RtpTransceiver, as described in
sec.applying-a-remote-desc.  If there are more RtpTransceivers than
there are m= sections, the unmatched RtpTransceivers will need to be
associated in a subsequent offer.
Paragraph (version B):
The next step is to generate m= sections for each m= section that is
present in the remote offer, as specified in RFC3264, Section 6.  For
the purposes of this discussion, any session-level attributes in the
offer that are also valid as media-level attributes are considered to
be present in each m= section.  Each offered m= section will have an
associated RtpTransceiver, as described in sec.applying-a-remote-
desc.  If there are more RtpTransceivers than there are m= sections,
the unmatched RtpTransceivers will need to be associated in a
subsequent offer.
Draft: draft-ietf-rtcweb-jsep

Commentary: I agree with justin here . my bad for missing that . 
 The 4th bullet on page 64 is ambiguous at " this m= section " . It looks like this bullet should just be merged with the previous bullet . 
 I 'm not sure what the problem is here , but I 'm not against merging it . 
 The bullet point in question is the one that reads If this m= section was present in the previous answer then the state of RTP / RTCP multiplexing MUST match what was previously negotiated . 
 LGTM
Paragraph (version A):
If the RTP/RTCP multiplexing policy is "require", each m= section
MUST contain an "a=rtcp-mux" attribute.  If an m= section contains
an "a=rtcp-mux-only" attribute then that section MUST also contain
an "a=rtcp-mux" attribute.
Paragraph (version A):
If this m= section was present in the previous answer then the
state of RTP/RTCP multiplexing MUST match what was previously
negotiated.
Paragraph (version B):
If the RTP/RTCP multiplexing policy is "require", each m= section
MUST contain an "a=rtcp-mux" attribute.  If an m= section contains
an "a=rtcp-mux-only" attribute, that section MUST also contain an
"a=rtcp-mux" attribute.
Paragraph (version B):
If an m= section was present in the previous answer, the state of
RTP/RTCP multiplexing MUST match what was previously negotiated.
Draft: draft-ietf-rtcweb-jsep

Commentary: The second paragraph of 6.8 starts " Next , " . I think it should start " First , " . 
 I agree with this .
Paragraph (version A):
Next, m= sections are processed.  For each m= section, the following
steps MUST be performed; if any parameters are out of bounds, or
cannot be applied, processing MUST stop and an error MUST be
returned.
Paragraph (version B):
First, m= sections are processed.  For each m= section, the following
steps MUST be performed; if any parameters are out of bounds, or
cannot be applied, processing MUST stop and an error MUST be
returned.
Draft: draft-ietf-rtcweb-jsep

Commentary: In the last paragraph of section 8 at " programmer MUST recognize " . That is not an appropriate use of 2119 . I suggest " needs to be aware " instead of " MUST recognize " . 
 This seems right
Paragraph (version A):
Conversely, the application programmer MUST recognize that the JS
does not have complete control of endpoint behavior.  One case that
bears particular mention is that editing ICE candidates out of the
SDP or suppressing trickled candidates does not have the expected
behavior: implementations will still perform checks from those
candidates even if they are not sent to the other side.  Thus, for
instance, it is not possible to prevent the remote peer from learning
your public IP address by removing server reflexive candidates.
Applications which wish to conceal their public IP address should
instead configure the ICE agent to use only relay candidates.
Paragraph (version B):
Conversely, the application programmer needs to be aware that the JS
does not have complete control of endpoint behavior.  One case that
bears particular mention is that editing ICE candidates out of the
SDP or suppressing trickled candidates does not have the expected
behavior: implementations will still perform checks from those
candidates even if they are not sent to the other side.  Thus, for
instance, it is not possible to prevent the remote peer from learning
your public IP address by removing server reflexive candidates.
Applications which wish to conceal their public IP address should
instead configure the ICE agent to use only relay candidates.
Draft: draft-ietf-rtcweb-jsep

Commentary: Fixed my own comment , now LGTM 
 I think this got all the text from  , it was just not a change so it does not show up in diff . 
 Suggested change to the first sentence of 1.1 OLD : The thinking behind WebRTC call setup has been to fully specify and control the media plane , but to leave the signaling plane up to the application as much as possible . New : WebRTC call setup has been designed to focus on controlling the media plane , leaving signaling plane behavior up to the application as much as possible . 
 OK
Paragraph (version A):
The thinking behind WebRTC call setup has been to fully specify and
control the media plane, but to leave the signaling plane up to the
application as much as possible.  The rationale is that different
applications may prefer to use different protocols, such as the
existing SIP call signaling protocol, or something custom to the
particular application, perhaps for a novel use case.  In this
approach, the key information that needs to be exchanged is the
multimedia session description, which specifies the necessary
transport and media configuration information necessary to establish
the media plane.
Paragraph (version B):
WebRTC call setup has been designed to focus on controlling the media
plane, leaving signaling plane behavior up to the application as much
as possible.  The rationale is that different applications may prefer
to use different protocols, such as the existing SIP call signaling
protocol, or something custom to the particular application, perhaps
for a novel use case.  In this approach, the key information that
needs to be exchanged is the multimedia session description, which
specifies the necessary transport and media configuration information
necessary to establish the media plane.
Draft: draft-ietf-rtcweb-jsep

Commentary: is meant to represent " direction in effect " , whereas represents " direction the application wants to negotiate " . So , the direction that both inspects and modifies should be ; its purpose is to change the application 's desired direction for a transceiver , regardless of the current state of negotiation . Also clarifying that also reflects the direction negotiated in a provisional answer , which was the intent ( I believe ) but was n't explicitly stated . This is consistent with it being the direction " in effect " , since applying a provisional answer allows the endpoint to start sending / receiving media . 
 do you want to look at this ? I believe this is straightforward . 
 Section 4.1.3 , removeTrack , states : This should say " transceiver.direction " . Using " currentDirection " does n't work because it may be null , and it also may result in un - intuitive behavior , where ends up not having any effect and results in a " sendrecv " or " sendonly " direction being negotiated . 
 Want to make a PR ?
Paragraph (version A):
The removeTrack method removes a MediaStreamTrack from the
PeerConnection, using the RtpSender argument to indicate which sender
should have its track removed.  The sender's track is cleared, and
the sender stops sending.  Future calls to createOffer will mark the
m= section associated with the sender as recvonly (if
transceiver.currentDirection is sendrecv) or as inactive (if
transceiver.currentDirection is sendonly).
Paragraph (version B):
The removeTrack method removes a MediaStreamTrack from the
PeerConnection, using the RtpSender argument to indicate which sender
should have its track removed.  The sender's track is cleared, and
the sender stops sending.  Future calls to createOffer will mark the
m= section associated with the sender as recvonly (if
transceiver.direction is sendrecv) or as inactive (if
transceiver.direction is sendonly).
Paragraph (version A):
The currentDirection property indicates the last negotiated direction
for the transceiver's associated m= section.  More specifically, it
indicates the RFC3264 directional attribute of the associated m=
section in the last applied answer, with "send" and "recv" directions
reversed if it was a remote answer.  For example, if the directional
attribute for the associated m= section in a remote answer is
"recvonly", currentDirection is set to "sendonly".
Paragraph (version B):
The currentDirection property indicates the last negotiated direction
for the transceiver's associated m= section.  More specifically, it
indicates the RFC3264 directional attribute of the associated m=
section in the last applied answer (including provisional answers),
with "send" and "recv" directions reversed if it was a remote answer.
For example, if the directional attribute for the associated m=
section in a remote answer is "recvonly", currentDirection is set to
"sendonly".
Draft: draft-ietf-rtcweb-jsep

Commentary: This addresses  's actual comment - and adds the first references to rollback in the processing section - but leaves the details to be filled in by a future PR . 
 LGTM
Paragraph (version A):
The setLocalDescription method instructs the PeerConnection to apply
the supplied session description as its local configuration.  The
type field indicates whether the description should be processed as
an offer, provisional answer, or final answer; offers and answers are
checked differently, using the various rules that exist for each SDP
line.
Paragraph (version B):
The setLocalDescription method instructs the PeerConnection to apply
the supplied session description as its local configuration.  The
type field indicates whether the description should be processed as
an offer, provisional answer, final answer, or rollback; offers and
answers are checked differently, using the various rules that exist
for each SDP line.
Paragraph (version A):
When creating offers, the transceiver direction is directly reflected
in the output, even for re-offers.  When creating answers, the
transceiver direction is intersected with the offered direction, as
explained in the sec.generating-an-answer section below.
Paragraph (version B):
When creating offers, the transceiver direction is directly reflected
in the output, even for re-offers.  When creating answers, the
transceiver direction is intersected with the offered direction, as
explained in sec.generating-an-answer below.
Paragraph (version A):
Next, the SessionDescription is parsed into a data structure, as
described in the sec.parsing-a-desc section below.
Paragraph (version A):
Finally, the parsed SessionDescription is applied as described in
the sec.applying-a-local-desc section below.
Paragraph (version B):
Next, the SessionDescription is parsed into a data structure, as
described in sec.parsing-a-desc below.
Paragraph (version B):
Finally, the parsed SessionDescription is applied as described in
sec.applying-a-local-desc below.
Paragraph (version A):
Next, the SessionDescription is parsed into a data structure, as
described in the sec.parsing-a-desc section below.  If parsing
fails for any reason, processing MUST stop and an error MUST be
returned.
Paragraph (version A):
Finally, the parsed SessionDescription is applied as described in
the sec.applying-a-remote-desc section below.
Paragraph (version B):
Next, the SessionDescription is parsed into a data structure, as
described in sec.parsing-a-desc below.  If parsing fails for any
reason, processing MUST stop and an error MUST be returned.
Paragraph (version B):
Finally, the parsed SessionDescription is applied as described in
sec.applying-a-remote-desc below.
Draft: draft-ietf-rtcweb-jsep

Commentary: re - offers may not always be right after an initial offer
Paragraph (version A):
If the initial offer was applied using setLocalDescription, and an
answer from the remote side has been applied using
setRemoteDescription, meaning the PeerConnection is in the "have-
remote-pranswer" or "stable" states, an offer is generated based on
the negotiated session descriptions by following the steps mentioned
for the "have-local-offer" state above.
Paragraph (version B):
If the previous offer was applied using setLocalDescription, and a
corresponding answer from the remote side has been applied using
setRemoteDescription, meaning the PeerConnection is in the "have-
remote-pranswer" or "stable" states, an offer is generated based on
the negotiated session descriptions by following the steps mentioned
for the "have-local-offer" state above.
Draft: draft-ietf-rtcweb-jsep

Commentary: This seems like a normative change . I 'm not saying I 'm against this , but what 's the rationale ? 
  's argument in , which I found to be convincing .
Paragraph (version A):
The receiver will first intersect any known local limits (e.g.,
hardware decoder capababilities, local policy) to determine the
absolute minimum and maximum sizes it can receive.  If there are no
known local limits, the "a=imageattr" attribute SHOULD be omitted.
Paragraph (version A):
Otherwise, an "a=imageattr" attribute is created with "recv"
direction, and the resulting resolution space formed from the
aforementioned intersection is used to specify its minimum and
maximum x= and y= values.  If the intersection is the null set, i.e.,
the degenerate case of no permitted resolutions, this MUST be
represented by x=0 and y=0 values.
Paragraph (version B):
The receiver will first intersect any known local limits (e.g.,
hardware decoder capababilities, local policy) to determine the
absolute minimum and maximum sizes it can receive.  If there are no
known local limits, the "a=imageattr" attribute SHOULD be omitted.
If these local limits preclude receiving any video, i.e., the
degenerate case of no permitted resolutions, the "a=imageattr"
attribute MUST be omitted, and the m= section MUST be marked as
sendonly/inactive, as appropriate.
Paragraph (version B):
Otherwise, an "a=imageattr" attribute is created with "recv"
direction, and the resulting resolution space formed from the
aforementioned intersection is used to specify its minimum and
maximum x= and y= values.
Paragraph (version A):
In the special case of a maximum resolution of [0, 0], as
described above, the sender MUST NOT transmit the encoding.
Draft: draft-ietf-rtcweb-jsep

Commentary: LGTMDid a few editorial tweaks , now LGTM .
Paragraph (version A):
If the m= section references any media formats, RTP header
extensions, or RTCP feedback mechanisms that were not present
in the corresponding m= section in the offer, this indicates a
negotiation problem and MUST result in an error.
Paragraph (version B):
If the m= section references RTCP feedback mechanisms that were
not present in the corresponding m= section in the offer, this
indicates a negotiation problem and MUST result in an error.
However, new media formats and new RTP header extension values
are permitted in the answer, as described in RFC3264,
Section 7, and RFC5285, Section 6.
Draft: draft-ietf-rtcweb-jsep

Commentary: any guess on what happened to these that caused them to not go in ? 
 They were somehow targeted to a branch other than master , and that branch was never merged 
 LGTM but you have a conflict
Paragraph (version A):
The media formats in the answer MAY include codecs present in the
offer that were discarded in a previous offer/answer exchange.
This is necessary for compatibility with third- party call control
and SIP use cases.
Paragraph (version A):
The m= line and corresponding "a=rtpmap" and "a=fmtp" lines MUST
only include codecs present in the most recent answer which have
not been excluded by the codec preferences of the associated
transceiver.  Note that non-JSEP endpoints are not subject to
these restrictions, and might offer media formats that were not
present in the most recent answer, as specified in RFC3264,
Section 8.  Therefore, JSEP implementations MUST be prepared to
receive such offers.
Paragraph (version A):
Unless codec preferences have been set for the associated
transceiver, the media formats on the m= line MUST be generated in
the same order as in the current local description.
Paragraph (version A):
The RTCP feedback extensions MUST only include those that are
present in the most recent answer.
Paragraph (version B):
The m= line and corresponding "a=rtpmap" and "a=fmtp" lines MUST
only include media formats which have not been excluded by the
codec preferences of the associated transceiver, and MUST include
all currently available formats.  Media formats that were
previously offered but are no longer available (e.g., a shared
hardware codec) MAY be excluded.
Paragraph (version B):
Unless codec preferences have been set for the associated
transceiver, the media formats on the m= line MUST be generated in
the same order as in the most recent answer.  Any media formats
that were not present in the most recent answer MUST be added
after all existing formats.
Paragraph (version B):
The RTCP feedback mechanisms MUST only include those that are
present in the most recent answer, except for the case of format-
specific mechanisms that are referencing a newly-added media
format.
Draft: draft-ietf-rtcweb-jsep

Commentary: I like the text in your comment and changed to that . 
 Worth taking an editorial pass over this if time permits 
 I prob have time to run this one down .
Paragraph (version A):
I-D.ietf-mmusic-sdp-mux-attributes groups SDP attributes into
different categories.  To avoid unnecessary duplication when bundling
I-D.ietf-mmusic-sdp-bundle-negotiation, Section 8.1, specifies that
attributes of category IDENTICAL or TRANSPORT MUST NOT be repeated in
bundled m= sections.  This includes m= sections for which bundling
has been negotiated and is still desired, as well as m= sections
marked as bundle-only.
Paragraph (version B):
I-D.ietf-mmusic-sdp-mux-attributes groups SDP attributes into
different categories.  To avoid unnecessary duplication when
bundling, attributes of category IDENTICAL or TRANSPORT MUST NOT be
repeated in bundled m= sections, as specified in I-D.ietf-mmusic-sdp-
bundle-negotiation, Section 8.1.  This includes m= sections for which
bundling has been negotiated and is still desired, as well as m=
sections marked as bundle-only.