Clarify client announce behavior when joining both swarms of a hybrid…

… torrent

beps/bep_0052.html

@@ -38,8 +38,8 @@ <h1><a href="../index.html">BitTorrent<span>.org</span></a></h1>
 <tr class="title field"><th class="docinfo-name">Title:</th><td class="field-body">The BitTorrent Protocol Specification v2</td>
 </tr>
 <tr><th class="docinfo-name">Version:</th>
-<td>7392d83f374b071ca9601728c27be2d05e199e0c</td></tr>
-<tr class="last-modified field"><th class="docinfo-name">Last-Modified:</th><td class="field-body">Thu Aug 31 15:47:00 2017 -0700</td>
+<td>ae25dd0950834632974c165f7953702a81764c94</td></tr>
+<tr class="last-modified field"><th class="docinfo-name">Last-Modified:</th><td class="field-body">Fri Jan 3 19:00:14 2020 +0100</td>
 </tr>
 <tr><th class="docinfo-name">Author:</th>
 <td>Bram Cohen &lt;<a class="reference external" href="mailto:bram&#37;&#52;&#48;bittorrent&#46;com">bram<span>&#64;</span>bittorrent<span>&#46;</span>com</a>&gt;</td></tr>
@@ -522,10 +522,21 @@ <h1>Upgrade Path</h1>
 is identical. During the download they must also verify that pieces match both piece
 hash formats. If any inconsistency is detected they may either abort or fall back to
 downloading one of the two formats as if the other were not present.</p>
+<p>Implementations supporting both formats which joined both swarms of a hybrid torrent
+MUST announce by making only one request containing both v1 (<tt class="docutils literal">info_hash</tt> key) and v2 info_hash (<tt class="docutils literal">info_hash_v2</tt> key).</p>
 <p>When initiating a connection and sending the sha1 infohash of such a hybrid torrent
 a peer can set the 4th most significant bit in the last byte of the reserved bitfield
 to indicate that it also supports the new format. The remote peer may then respond
 with the new infohash to upgrade the connect to the new format.</p>
+<div class="section" id="examples">
+<h2>Examples</h2>
+<p>Example announce string for a hybrid torrent for implementations supporting both
+formats:</p>
+<pre class="literal-block">
+GET /announce?peer_id=aaaaaaaaaaaaaaaaaaaa&amp;info_hash=bbbbbbbbbbbbbbbbbbbb&amp;info_hash_v2=cccccccccccccccccccc
+&amp;port=6881&amp;left=50&amp;downloaded=100&amp;uploaded=30&amp;compact=1
+</pre>
+</div>
 </div>
 <div class="section" id="resources">
 <h1>Resources</h1>

beps/bep_0052.rst

@@ -570,12 +570,22 @@ is identical. During the download they must also verify that pieces match both p
 hash formats. If any inconsistency is detected they may either abort or fall back to
 downloading one of the two formats as if the other were not present.
 
+Implementations supporting both formats which joined both swarms of a hybrid torrent
+MUST announce by making only one request containing both v1 (``info_hash`` key) and v2 info_hash (``info_hash_v2`` key).
+
 When initiating a connection and sending the sha1 infohash of such a hybrid torrent
 a peer can set the 4th most significant bit in the last byte of the reserved bitfield
 to indicate that it also supports the new format. The remote peer may then respond
 with the new infohash to upgrade the connect to the new format.   
 
+Examples
+========
+
+Example announce string for a hybrid torrent for implementations supporting both
+formats::
 
+	GET /announce?peer_id=aaaaaaaaaaaaaaaaaaaa&info_hash=bbbbbbbbbbbbbbbbbbbb&info_hash_v2=cccccccccccccccccccc
+	&port=6881&left=50&downloaded=100&uploaded=30&compact=1
 
 ---------
 Resources