From b2deca8c83a8f235779cedec5dee32ffcb851d7d Mon Sep 17 00:00:00 2001 From: Emily Morehouse Date: Mon, 22 May 2017 12:03:53 -0700 Subject: [PATCH] Add description of how the directory structure targets Python versions. (#1288) --- CONTRIBUTING.md | 20 +++++++++++++++++--- 1 file changed, 17 insertions(+), 3 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 27ecd5688..86e2ac02f 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -170,9 +170,23 @@ contributors. There are separate directories for `stdlib` and `third_party` stubs. Within those, there are separate directories for different versions of -Python the stubs target. If the given library works on both Python 2 -and Python 3, prefer to put your stubs in an `2and3` directory, unless -the types are so different that the stubs become unreadable that way. +Python the stubs target. + +The directory name indicates the major version of Python that a stub targets +and optionally the lowest minor version, with the exception of the `2and3` +directory which applies to both Python 2 and 3. + +For example, stubs in the `3` directory will be applied to all versions of +Python 3, though stubs in the `3.6` directory will only be applied to versions +3.6 and above. However, stubs in the `2` directory will not be applied to +Python 3. + +It is preferred to use a single stub in the more generic directory that +conditionally targets specific versions when needed, as opposed +to maintaining multiple stub files within more specific directories. Similarly, +if the given library works on both Python 2 and Python 3, prefer to put your +stubs in the `2and3` directory, unless the types are so different that the stubs +become unreadable that way. You can use checks like `if sys.version_info >= (3, 4):` to denote new functionality introduced in a given Python version or solve type