gh-114785: Remove Porting from Python2 how-to

[sobolevn]

I feel a pleasant warmth inside by proposing this change 😆

However, I don't insist on making it: it might still be useful for someone, even outdated.
In my opinion - it is not really helpful anymore.

• Issue: "Porting Python2 to Python3" recommends tools that no longer support Python2 #114785

---

📚 Documentation preview 📚: https://cpython-previews--114805.org.readthedocs.build/en/114805/howto/pyporting.html

[hugovk]

This page does have some traffic.

From the Plausible 30-day trial, /3/howto/pyporting.html was number 266 out of 14,767 pages, with 3,995 views. That's a bit less than the 4,016 views for the Spanish homepage: /es/3/.

Instead of outright deleting and serving a 404 to visitors, can we avoid contributing to linkrot and put something else useful on the page?

Are there some useful external resources we can link to?

[sobolevn]

@hugovk great that we have these numbers! I didn't know we collect them.
I am open to suggestions about the content we can put there. Last time I used a Python2 project was like 10 years ago, so I am not an expert here.

[hugovk]

This guide by Fedora looks good: https://portingguide.readthedocs.io

Here's a 2.5 hour PyCon 2020 tutorial: https://www.youtube.com/watch?v=JgIgEjASOlk

And a tutorial by Digital Ocean: https://www.digitalocean.com/community/tutorials/how-to-port-python-2-code-to-python-3

And by ActiveState: https://www.activestate.com/blog/how-to-migrate-python-2-applications-to-python-3/

We could keep these three paragraphs from the abstract (shift them out of the abstract and delete the abstract):

Python 2 reached its official end-of-life at the start of 2020. This means that no new bug reports, fixes, or changes will be made to Python 2 - it’s no longer supported.

If you are looking to port an extension module instead of pure Python code, please see Porting Extension Modules to Python 3.

The archived python-porting mailing list may contain some useful guidance.

And add links to:

• Status of Python versions
• PEP 373 – Python 2.7 Release Schedule

And then links to those resources.

[brettcannon]

Is there any reason not to think that search engines won't update to the e.g. 3.12 version of that page?

[sobolevn]

Is there any reason not to think that search engines won't update to the e.g. 3.12 version of that page?

Sorry, I don't understand your question :(

[hugovk]

I think the question is:

If we delete the page at https://docs.python.org/3/howto/pyporting.html, will search engines stop suggesting it and instead start suggesting https://docs.python.org/3.12/howto/pyporting.html?

Maybe they will? SEO is a mysterious art. We still sometimes get reports that old version pages shown up results.

We do have this in the 3.12 page which tells search engines the canonical page is the one deleted in this PR, which might confuse things:

<link rel="canonical" href="https://docs.python.org/3/howto/pyporting.html" />

Perhaps we can change that to point to /3.12/ just for this page (also in /3.11/?

In any case, even if search engines do start pointing to /3.12/, it won't fix linkrot -- it won't fix other websites that link to https://docs.python.org/3/howto/pyporting.html

To sort that, we should either keep a stub page, or figure out some redirects from https://docs.python.org/3/howto/pyporting.html to elsewhere.

I favour a stub page.

[vstinner]

LGTM.

[encukou]

Replacing it with a stub and link list, as @hugovk suggested (and as we did for cporting-howto), sounds good to me. That way, people who end up there have a place to go.

(Disclosure: I “maintain” Fedora's guide. Not that there's much to maintain there, with the disclaimer that it'll get you up to Python 3.6 and then you're on your own.)

Is it possible to remove it from the rendered tables of contents? That might be appropriate too.

[hugovk]

Is it possible to remove it from the rendered tables of contents? That might be appropriate too.

Yes, with :orphan::

https://www.sphinx-doc.org/en/master/usage/restructuredtext/field-lists.html#special-metadata-fields

For example:

• https://github.com/python/cpython/blob/main/Doc/distributing/index.rst?plain=1
• https://github.com/python/cpython/blob/main/Doc/howto/clinic.rst?plain=1

[hugovk]

Thanks, looking good!

I remove my review since the PR changed

[sobolevn]

Anything else left to do? Or can we proceed? :)

[hugovk]

I think this is ready to merge, would you like to use your new powers and do the honours? :)

[sobolevn]

Sure 🎉

[miss-islington-app]

Thanks @sobolevn for the PR 🌮🎉.. I'm working now to backport this PR to: 3.11, 3.12.
🐍🍒⛏🤖

[bedevere-app]

GH-115327 is a backport of this pull request to the 3.12 branch.

[bedevere-app]

GH-115328 is a backport of this pull request to the 3.11 branch.

[sobolevn]

@hugovk I am not sure about the backports. Maybe we should keep older versions as-is?

[encukou]

Please don't backport a removal.
(If you do, update the version in “Since Python 3.13 the original porting guide was discontinued.”)

[hugovk]

The reason for making these changes was to help people because the existing info is outdated and points to tools that don't support Python 2, and they'll struggle if they try and follow the advice.

If we don't backport to 3.12 (= /3/ default docs), people will still see the outdated, unhelpful information for another six months (until 3.13 is released).

I think it should at least be backported to 3.12.

Similarly for 3.11: we want people to have helpful information. Let's put that in front of people in as many places as possible (= bugfix branches).

(If you do, update the version in “Since Python 3.13 the original porting guide was discontinued.”)

Good point, and update the link to point to the last version with the old guide.

[sobolevn]

I also have

`archive <https://docs.python.org/3.12/howto/pyporting.html>`_. 

link in the new docs, so I would have to update it to be 3.11 if we backport to 3.12

I see pros and cons with both ways, I will listen to others here :)