Tutorial for phasing out Python versions #459

tonybaloney · 2018-03-21T23:06:25Z

See #450 for discussion

hugovk

Looks good, just some little nitpicks.

hugovk · 2018-03-22T06:54:57Z

source/guides/dropping-older-python-versions.rst

+
+Dropping support for older Python versions is supported by the standard :ref:`core-metadata` 1.2 specification via a "Requires-Python" attribute.
+
+Metadata 1.2+ clients, such as Pip 9.0+ will adhere to this specification by matching the current Python runtime and comparing it with the required version 


... clients, such as Pip 9.0+ will ...

This comma acts parenthetically. So either a closing one is needed:

... clients, such as Pip 9.0+, will ...

Or the opening one not needed:

... clients such as Pip 9.0+ will ...

hugovk · 2018-03-22T06:58:51Z

source/guides/dropping-older-python-versions.rst

+Metadata 1.2+ clients, such as Pip 9.0+ will adhere to this specification by matching the current Python runtime and comparing it with the required version 
+in the package metadata. If they do not match, it will attempt to install the last package distribution that supported that Python runtime.
+
+This mechanism can be leveraged to drop support for older Python versions, by amending the "Requires-Python" attribute in the package metadata.


Use plain language:

"leveraged" - > "used"

https://content-guide.18f.gov/plain-language/
https://ig.ft.com/sites/guffipedia/leverage/

hugovk · 2018-03-22T07:02:49Z

source/guides/dropping-older-python-versions.rst

+
+This workflow requires that:
+
+1. The publisher be using the latest version of :ref:`setuptools`,


-> "The publisher is using"

hugovk · 2018-03-22T07:03:09Z

source/guides/dropping-older-python-versions.rst

+This workflow requires that:
+
+1. The publisher be using the latest version of :ref:`setuptools`,
+2. The latest version of :ref:`twine` be used to upload the package,


-> "is used"

hugovk · 2018-03-22T07:05:06Z

source/guides/dropping-older-python-versions.rst

+Defining the Python version required
+------------------------------------
+
+1. Download the newest version of Setuptools


The requirements also say the latest version of Pip and Twine are needed.

Shall we make this section cover all of those, and update the command to pip install --upgrade pip setuptools twine all at once?

Or, because Pip can be a bit of a special case, at least for Setuptools and Twine.

hugovk · 2018-03-22T07:22:56Z

source/guides/dropping-older-python-versions.rst

+4. Using Twine to publish
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Twine has a number of advantages, apart from being faster is now the supported method for publishing packages.


Add "it" -> "apart from being faster it is now"

hugovk · 2018-03-22T07:23:40Z

source/guides/dropping-older-python-versions.rst

+
+It must be done in this order for the automated fail-back to work.
+
+For example, if you published the Requires-Python: ">=2.7" as version 1.0.0 of your package.


Remove "if"

hugovk · 2018-03-22T07:24:22Z

source/guides/dropping-older-python-versions.rst

+
+For example, if you published the Requires-Python: ">=2.7" as version 1.0.0 of your package.
+
+If you were then to update the version string to ">=3.5", and publish a new version, 2.0.0 of your package, any users running pip 9.0+ from version 2.7 of Python will


Remove comma:
-> "publish a new version 2.0.0 of your package"

hugovk · 2018-03-22T07:24:46Z

source/guides/dropping-older-python-versions.rst

+
+For example, if you published the Requires-Python: ">=2.7" as version 1.0.0 of your package.
+
+If you were then to update the version string to ">=3.5", and publish a new version, 2.0.0 of your package, any users running pip 9.0+ from version 2.7 of Python will


Caps:
-> "Pip 9.0+"

hugovk · 2018-03-22T07:25:58Z

source/guides/dropping-older-python-versions.rst

+
+For example, if you published the Requires-Python: ">=2.7" as version 1.0.0 of your package.
+
+If you were then to update the version string to ">=3.5", and publish a new version, 2.0.0 of your package, any users running pip 9.0+ from version 2.7 of Python will


"from version 2.7 of Python will"
->
"from Python 2.7 will"

tonybaloney · 2018-03-22T09:09:18Z

@hugovk all comments taken into account in 003466d

tonybaloney · 2018-03-22T09:09:41Z

and thank you for the thorough review! You are quite the wordsmith :-)

ncoghlan

This looks excellent, thank you! There's just the one actual change request in my comments: adding a note at the top about the guide being distutils/setuptools centric. I think that's fine given that this guide is focused on long-lived projects that are most likely to be using one or the other of those projects (or a closely related derivative, like d2to1), but we should call it out so that folks using newer publishing tools like flit know they'll need to look at the flit documentation for additional details.

The rest of my comments are take-it-or-leave-it comments where we can easily postpone doing anything about them.

ncoghlan · 2018-03-22T11:08:28Z

source/guides/dropping-older-python-versions.rst

+
+1. The publisher is using the latest version of :ref:`setuptools`,
+2. The latest version of :ref:`twine` is used to upload the package,
+3. The user installing the package has at least Pip 9.0, or a client that supports the Metadata 1.2 specification.


There's potentially a 4th requirement here, which is that the package index server has to populate the data-requires-python link attribute described in PEP 503. Both pypi.org (the warehouse codebase) and pypi.python.org (the legacy PyPI codebase) do that, but we're not sure about the various caching proxies that are out there - those may confound the client's version requirement detection.

However, I think we can leave that out for now, and potentially add it if folks report problems that get traced back to that issue.

I'll leave this out I think

ncoghlan · 2018-03-22T11:14:45Z

source/guides/dropping-older-python-versions.rst

+in the package metadata. If they do not match, it will attempt to install the last package distribution that supported that Python runtime.
+
+This mechanism can be used to drop support for older Python versions, by amending the "Requires-Python" attribute in the package metadata.
+


We should include a caveat here that this guide is specifically for users of setuptools, or users of distutils that will need to upgrade to setuptools in order to be able to include the Requires-Python field in their metadata.

Users of other packaging tools will need to consult the relevant project's documentation on how to set Requires-Python, but the general approach described here will otherwise hold.

added in top comment

ncoghlan · 2018-03-22T11:18:44Z

source/guides/dropping-older-python-versions.rst

+3. Validating the Metadata before publishing
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Within a Python source package (the zip or the tar-gz file you download) is a text file called PKG-INFO.


While I think this section will be fine if we add an "Aimed at distutils/setuptools users" caveat at the top, it does suggest to me that a twine upload --dry-run option that printed out the headers that would be sent without actually making a POST request to the server could be very helpful. (I'll add a comment to pypa/twine#207 pointing back to this PR as an example use case)

ncoghlan · 2018-03-22T11:22:46Z

source/guides/dropping-older-python-versions.rst

+4. Using Twine to publish
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Twine has a number of advantages, apart from being faster it is now the supported method for publishing packages.


In addition to mentioning support here, I'd also suggest noting that it's the most reliable when it comes to correctly passing the artifact metadata to the publication server (the server doesn't inspect the artifacts directly - it relies on the client to supply the relevant metadata).

tonybaloney · 2018-04-03T01:14:48Z

@ncoghlan added a comment in a04ed9c

ncoghlan · 2018-04-03T12:37:26Z

Thank you! Merged, and already up at https://packaging.python.org/guides/dropping-older-python-versions/ :)

ncoghlan · 2018-04-03T12:45:43Z

I spotted a couple of things in the rendered version that I'd missed on review: e88a088

tonybaloney added 3 commits March 13, 2018 13:05

add stubs for new tutorials on adding older python versions #450

86e3716

start draft for tutorial

fb3f510

new tutorial for phasing out Python versions

d6c9570

hugovk approved these changes Mar 22, 2018

View reviewed changes

amendments from code review

003466d

now now

8f171d7

ncoghlan requested changes Mar 22, 2018

View reviewed changes

add nick's comments

a04ed9c

ncoghlan approved these changes Apr 3, 2018

View reviewed changes

ncoghlan merged commit 9cadc66 into pypa:master Apr 3, 2018

ncoghlan mentioned this pull request Apr 3, 2018

Guide request: gracefully dropping support for older Python versions #450

Closed


		Dropping support for older Python versions is supported by the standard :ref:`core-metadata` 1.2 specification via a "Requires-Python" attribute.

		Metadata 1.2+ clients, such as Pip 9.0+ will adhere to this specification by matching the current Python runtime and comparing it with the required version


		This workflow requires that:

		1. The publisher be using the latest version of :ref:`setuptools`,


		It must be done in this order for the automated fail-back to work.

		For example, if you published the Requires-Python: ">=2.7" as version 1.0.0 of your package.


		For example, if you published the Requires-Python: ">=2.7" as version 1.0.0 of your package.

		If you were then to update the version string to ">=3.5", and publish a new version, 2.0.0 of your package, any users running pip 9.0+ from version 2.7 of Python will

		in the package metadata. If they do not match, it will attempt to install the last package distribution that supported that Python runtime.

		This mechanism can be used to drop support for older Python versions, by amending the "Requires-Python" attribute in the package metadata.

Tutorial for phasing out Python versions #459

Tutorial for phasing out Python versions #459

Uh oh!

Conversation

tonybaloney commented Mar 21, 2018

Uh oh!

hugovk left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

tonybaloney commented Mar 22, 2018

Uh oh!

tonybaloney commented Mar 22, 2018

Uh oh!

ncoghlan left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

tonybaloney commented Apr 3, 2018

Uh oh!

ncoghlan commented Apr 3, 2018

Uh oh!

ncoghlan commented Apr 3, 2018

Uh oh!

Uh oh!