1 files changed, 36 insertions, 3 deletions
diff --git a/guide/porting.html b/guide/porting.html
index 8b073d6..04d48e4 100644
--- a/guide/porting.html
+++ b/guide/porting.html
@@ -73,8 +73,35 @@ PR#14349</a> for an example of impact and a fix.</p>
 </div>
 </section>
 </section>
+<section id="experimental-python-implementations">
+<h2>Experimental Python implementations<a class="headerlink" href="#experimental-python-implementations" title="Link to this heading">¶</a></h2>
+<section id="pypy">
+<h3>PyPy<a class="headerlink" href="#pypy" title="Link to this heading">¶</a></h3>
+<p>PyPy is using JIT to run Python code which can result in significant
+performance improvements in some workflows, but it could also penalize
+other programs.</p>
+<p>In particular, calls to compiled extensions can penalize PyPy severely.
+For this reason, it is generally recommended to skip building “speedup”
+extensions for PyPy — in fact, upstream build systems frequently do that
+automatically.  A common approach is to combine checks for PyPy with
+<code class="docutils literal notranslate"><span class="pre">native-extensions</span></code> USE flag:</p>
+<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>python_compile<span class="o">()</span><span class="w"> </span><span class="o">{</span>
+<span class="w">    </span><span class="k">if</span><span class="w"> </span>!<span class="w"> </span>use<span class="w"> </span>native-extensions<span class="w"> </span><span class="o">||</span><span class="w"> </span><span class="o">[[</span><span class="w"> </span><span class="si">${</span><span class="nv">EPYTHON</span><span class="si">}</span><span class="w"> </span><span class="o">==</span><span class="w"> </span>pypy3<span class="w"> </span><span class="o">]]</span><span class="p">;</span><span class="w"> </span><span class="k">then</span>
+<span class="w">        </span><span class="nb">local</span><span class="w"> </span>-x<span class="w"> </span><span class="nv">MULTIDICT_NO_EXTENSIONS</span><span class="o">=</span><span class="m">1</span>
+<span class="w">    </span><span class="k">fi</span>
+
+<span class="w">    </span>distutils-r1_python_compile
+<span class="o">}</span>
+</pre></div>
+</div>
+<p>However, this does not imply that Python packages largely based
+on C extensions should not be marked for PyPy3 compatibility.
+For example, while packages such as Pandas can be less performant
+under PyPy, they could be used as a part of larger program that overall
+benefits from running under PyPy.</p>
+</section>
 <section id="freethreading-cpython-versions">
-<span id="index-0"></span><h2>Freethreading CPython versions<a class="headerlink" href="#freethreading-cpython-versions" title="Link to this heading">¶</a></h2>
+<span id="index-0"></span><h3>Freethreading CPython versions<a class="headerlink" href="#freethreading-cpython-versions" title="Link to this heading">¶</a></h3>
 <p>CPython is used the so-called “global interpreter lock” to prevent
 multiple threads from executing Python code simultaneously.  It was
 designed like this to simplify implementation, but at the cost of
@@ -100,7 +127,12 @@ and therefore defeat the purpose of freethreading build.  To determine
 whether a C extension supports freethreading mode, grep the code
 for <code class="docutils literal notranslate"><span class="pre">Py_MOD_GIL_NOT_USED</span></code>.  CPython will also verbosely warn upon
 importing extensions without this support.</p>
-<p>In general, do not add <code class="docutils literal notranslate"><span class="pre">python3_13t</span></code> to <code class="docutils literal notranslate"><span class="pre">PYTHON_COMPAT</span></code>
+<p>In general, do not add <code class="docutils literal notranslate"><span class="pre">python3_13t</span></code> to <code class="docutils literal notranslate"><span class="pre">PYTHON_COMPAT</span></code> in leaf
+packages, unless they make use of multithreading and have real gain
+from freethreaded versions — otherwise, it may actually be slower than
+the regular variant.</p>
+<p>For dependency packages, add <code class="docutils literal notranslate"><span class="pre">python3_13t</span></code> only after explicitly
+testing that the package in question works.  Do not add it
 if the package in question installs extensions that do not support
 freethreading.  This would penalize the setup, prevent proper testing
 and therefore defeat the purpose of separately specifying this target.
@@ -108,6 +140,7 @@ Preferably, wait until they do.  For some common dependencies, adding it
 may be acceptable, provided that the extensions are optional and that
 they are not built for freethreading targets.</p>
 </section>
+</section>
 <section id="python-3-13">
 <h2>Python 3.13<a class="headerlink" href="#python-3-13" title="Link to this heading">¶</a></h2>
 <p>See also: <a class="reference external" href="https://docs.python.org/3.13/whatsnew/3.13.html">what’s new in Python 3.13</a></p>
@@ -673,7 +706,7 @@ modules need to be imported and used separately rather than one.</p>
 <li class="toctree-l1"><a class="reference internal" href="buildsys.html">Integration with build systems written in Python</a></li>
 <li class="toctree-l1 current"><a class="current reference internal" href="#">Porting tips</a><ul>
 <li class="toctree-l2"><a class="reference internal" href="#retroactive-changes">Retroactive changes</a></li>
-<li class="toctree-l2"><a class="reference internal" href="#freethreading-cpython-versions">Freethreading CPython versions</a></li>
+<li class="toctree-l2"><a class="reference internal" href="#experimental-python-implementations">Experimental Python implementations</a></li>
 <li class="toctree-l2"><a class="reference internal" href="#python-3-13">Python 3.13</a></li>
 <li class="toctree-l2"><a class="reference internal" href="#python-3-12">Python 3.12</a></li>
 <li class="toctree-l2"><a class="reference internal" href="#python-3-11">Python 3.11</a></li>