diff options
Diffstat (limited to 'guide/package-maintenance.html')
| -rw-r--r-- | guide/package-maintenance.html | 82 |
1 files changed, 70 insertions, 12 deletions
diff --git a/guide/package-maintenance.html b/guide/package-maintenance.html index d64c17f..539518b 100644 --- a/guide/package-maintenance.html +++ b/guide/package-maintenance.html @@ -110,16 +110,11 @@ an empty package to reserve the name.</p> </section> <section id="support-for-python-2"> <h2>Support for Python 2<a class="headerlink" href="#support-for-python-2" title="Link to this heading">¶</a></h2> -<p>Since Python 2.7 reached EOL, Gentoo is currently phasing out support -for Python 2. Unless your package or its reverse dependencies really -need it, you should omit it from <code class="docutils literal notranslate"><span class="pre">PYTHON_COMPAT</span></code>. If you’re adding -a new package and it does not support Python 3, do not add it.</p> -<p>Many upstreams are removing Python 2 support from new releases of their -software. We remove it proactively whenever reverse dependencies permit -in order to anticipate this and avoid having to deal with lots -of reverse dependencies afterwards.</p> -<p>Packages that do not support Python 3 and are unlikely to start -supporting it soon are being slowly removed.</p> +<p>Gentoo does not support building Python packages for Python 2 anymore. +We are keeping PyPy2.7 (built stripped down, by default) to facilitate +building PyPy3, and CPython 2.7 for PyPy2.7 bootstrap. Technically, +they could still be used to run Python 2 code standalone, but this +is discouraged and poses security risk.</p> </section> <section id="which-implementations-to-test-new-packages-for"> <h2>Which implementations to test new packages for?<a class="headerlink" href="#which-implementations-to-test-new-packages-for" title="Link to this heading">¶</a></h2> @@ -167,8 +162,8 @@ the dependencies of Portage prematurely. This generally includes dependencies.</p> <p>Ideally, these ebuilds carry an appropriate note above their EAPI line, e.g.:</p> -<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1"># please keep this ebuild at EAPI 7 -- sys-apps/portage dep</span> -<span class="n">EAPI</span><span class="o">=</span><span class="mi">7</span> +<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span><span class="c1"># please keep this ebuild at EAPI 7 -- sys-apps/portage dep</span> +<span class="nv">EAPI</span><span class="o">=</span><span class="m">7</span> </pre></div> </div> <p>This does not apply to test dependencies — they are not strictly @@ -211,6 +206,68 @@ version numbers that do not have a clear mapping to Gentoo version syntax (e.g. <code class="docutils literal notranslate"><span class="pre">.post</span></code> releases).</p> </section> </section> +<section id="stabilization-recommendations"> +<h2>Stabilization recommendations<a class="headerlink" href="#stabilization-recommendations" title="Link to this heading">¶</a></h2> +<section id="policy"> +<h3>Policy<a class="headerlink" href="#policy" title="Link to this heading">¶</a></h3> +<p>The Python landscape is changing dynamically, and therefore the test +suites in packages — if not whole packages — often start failing early. +For this reason, we recommend lowering the baseline stabilization delay +to 14 days.</p> +<p>In addition to that:</p> +<ol class="arabic simple"> +<li><p>When stabilizing across a major version bump (e.g. from 1.1.x +to 1.2.x), prefer waiting until the newest minor version becomes +the stable candidate (i.e. do not stabilize from 1.1.4 to 1.2.0 +if 1.2.1 is available). When stabilizing over a minor version bump +(e.g. from 1.1.4 to 1.1.5), feel free to proceed immediately.</p></li> +<li><p>If reverse dependencies block upgrade of a package (e.g. through +<code class="docutils literal notranslate"><span class="pre"><</span></code> dependencies), consider stabilizing the newest versions +matching the restriction as well. The same is worth considering +if upstream maintains multiple versions simultaneously with major +API changes, even if there are no explicit <code class="docutils literal notranslate"><span class="pre"><</span></code> dependencies +(e.g. <code class="docutils literal notranslate"><span class="pre">dev-python/django</span></code>).</p></li> +<li><p>If a new release is likely to cause major compatibility issues +(e.g. major releases of <code class="docutils literal notranslate"><span class="pre">dev-python/sphinx</span></code>), consider delaying +the stabilization and/or explicitly testing its reverse dependencies, +in order to ensure that necessary <code class="docutils literal notranslate"><span class="pre"><</span></code> dependencies are added first.</p></li> +<li><p>Avoid stabilizing prereleases (alpha, beta and RC versions), unless +it is necessary and upstream does not provide a final release +for a significant time.</p></li> +<li><p>Ideally, aim for tests to pass on all relevant architectures. Add +deselects if necessary, as this will ensure that future +stabilizations will be handled faster.</p></li> +</ol> +</section> +<section id="tooling"> +<h3>Tooling<a class="headerlink" href="#tooling" title="Link to this heading">¶</a></h3> +<p>The recommended way of filing stabilization requests is to use +<code class="docutils literal notranslate"><span class="pre">stablereq-*</span></code> tools from <code class="docutils literal notranslate"><span class="pre">app-portage/mgorny-dev-scripts</span></code> package, +combined with <code class="docutils literal notranslate"><span class="pre">pkgdev</span></code> from <code class="docutils literal notranslate"><span class="pre">dev-util/pkgdev</span></code>.</p> +<p>To prepare the initial stabilization list and open it in an editor:</p> +<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span><span class="nb">export</span><span class="w"> </span><span class="nv">PKGCHECK_ARGS</span><span class="o">=</span><span class="s2">"--stabletime 14"</span> +git<span class="w"> </span>grep<span class="w"> </span>-l<span class="w"> </span>python@<span class="w"> </span><span class="s1">'**/metadata.xml'</span><span class="w"> </span><span class="p">|</span> +<span class="w"> </span>cut<span class="w"> </span>-d/<span class="w"> </span>-f1-2<span class="w"> </span><span class="p">|</span> +<span class="w"> </span>grep<span class="w"> </span>-v<span class="w"> </span>dev-python/<span class="w"> </span><span class="p">|</span> +<span class="w"> </span>xargs<span class="w"> </span>stablereq-make-list<span class="w"> </span><span class="s1">'dev-python/*'</span> +</pre></div> +</div> +<p>Simultaneously, the following call can be used to run <code class="docutils literal notranslate"><span class="pre">eshowkw</span></code> +to display current keywords on all stabilization candidates:</p> +<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span><span class="nb">export</span><span class="w"> </span><span class="nv">PKGCHECK_ARGS</span><span class="o">=</span><span class="s2">"--stabletime 14"</span> +git<span class="w"> </span>grep<span class="w"> </span>-l<span class="w"> </span>python@<span class="w"> </span><span class="s1">'**/metadata.xml'</span><span class="w"> </span><span class="p">|</span> +<span class="w"> </span>cut<span class="w"> </span>-d/<span class="w"> </span>-f1-2<span class="w"> </span><span class="p">|</span> +<span class="w"> </span>grep<span class="w"> </span>-v<span class="w"> </span>dev-python/<span class="w"> </span><span class="p">|</span> +<span class="w"> </span>xargs<span class="w"> </span>stablereq-eshowkw<span class="w"> </span><span class="s1">'dev-python/*'</span> +</pre></div> +</div> +<p>Edit the list as desirable, save into a file and then feed the file +into pkgdev:</p> +<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>pkgdev<span class="w"> </span>bugs<span class="w"> </span>--auto-cc-arches<span class="o">=</span>*<span class="w"> </span><span class="k">$(</span><<span class="s2">"</span><span class="si">${</span><span class="nv">file_path</span><span class="si">}</span><span class="s2">"</span><span class="k">)</span> +</pre></div> +</div> +</section> +</section> <section id="routine-checks-on-installed-python-packages"> <h2>Routine checks on installed Python packages<a class="headerlink" href="#routine-checks-on-installed-python-packages" title="Link to this heading">¶</a></h2> <p>The following actions are recommended to be run periodically on systems @@ -369,6 +426,7 @@ than to copy the mistakes into the ebuild.</p> <li class="toctree-l2"><a class="reference internal" href="#which-packages-can-be-co-maintained-by-the-python-project">Which packages can be (co-)maintained by the Python project?</a></li> <li class="toctree-l2"><a class="reference internal" href="#porting-packages-to-a-new-eapi">Porting packages to a new EAPI</a></li> <li class="toctree-l2"><a class="reference internal" href="#monitoring-new-package-versions">Monitoring new package versions</a></li> +<li class="toctree-l2"><a class="reference internal" href="#stabilization-recommendations">Stabilization recommendations</a></li> <li class="toctree-l2"><a class="reference internal" href="#routine-checks-on-installed-python-packages">Routine checks on installed Python packages</a></li> </ul> </li> |