From dd57c717a780ffa7226bd01fb61fd09f0ba2934c Mon Sep 17 00:00:00 2001 From: Tom Augspurger Date: Thu, 12 Sep 2019 10:59:52 -0500 Subject: [PATCH 1/7] Added version policy --- doc/source/development/index.rst | 1 + doc/source/development/policies.rst | 40 +++++++++++++++++++++++++++++ doc/source/whatsnew/v1.0.0.rst | 36 +++++++++++++++++++++++--- 3 files changed, 73 insertions(+), 4 deletions(-) create mode 100644 doc/source/development/policies.rst diff --git a/doc/source/development/index.rst b/doc/source/development/index.rst index c7710ff19f078..1228f00667f3a 100644 --- a/doc/source/development/index.rst +++ b/doc/source/development/index.rst @@ -16,4 +16,5 @@ Development internals extending developer + policies roadmap diff --git a/doc/source/development/policies.rst b/doc/source/development/policies.rst new file mode 100644 index 0000000000000..b9d310c841306 --- /dev/null +++ b/doc/source/development/policies.rst @@ -0,0 +1,40 @@ +.. _develop.policies: + +******** +Policies +******** + +.. _policies.version: + +Version Policy +~~~~~~~~~~~~~~ + +.. versionchanged:: 1.0.0 + +Pandas uses a version of `SemVer`_ to govern deprecations, API compatibility, and version numbering. + +A pandas release number is made up of ``MAJOR.MINOR.PATCH``. + +API breaking changes should only occur in **major** releases. Theses changes will be documented, +with clear guidance on what is changing, why it's changing, and how to migrate existing code to the +new beahvior. + +Whenever possible, a deprecation path will be provided rather than an outright breaking change. + +Pandas will introduce deprecations in **major** or **minor** releases. These deprecations will +preserve the existing behavior while emitting a warning that provide guidance + +* How to achieve similar behavior if an alternative is available +* The pandas version in which the deprecation will be enforced. + +We will not introduce new deprecations in patch releases. + +Deprecations will only be enforced in **major** releases. + +.. note:: + + Pandas will sometimes make *behavior changing* bug fixes, as part of + minor or patch releases. Whether or not a change is a bug fix or an + API-breaking change is a judgement call. We'll do our best, and we + invite you to participate in development discussion on the issue + tracker or mailing list. diff --git a/doc/source/whatsnew/v1.0.0.rst b/doc/source/whatsnew/v1.0.0.rst index 71374a3bff692..a51b1f58e4963 100644 --- a/doc/source/whatsnew/v1.0.0.rst +++ b/doc/source/whatsnew/v1.0.0.rst @@ -3,10 +3,38 @@ What's new in 1.0.0 (??) ------------------------ -.. warning:: - - Starting with the 0.25.x series of releases, pandas only supports Python 3.5.3 and higher. - See `Dropping Python 2.7 `_ for more details. +New Deprecation Policy +~~~~~~~~~~~~~~~~~~~~~~ + +Starting with Pandas 1.0.0, pandas will adopt a version of `SemVer`_. + +Historically, pandas has used a "rolling" deprecation policy, with occasional +outright breaking API changes. Where possible, we would deprecate the behavior +we'd like to change, giving an option to adopt the new behavior (via a keyword +or an alternative method), and issuing a warning for users of the old behavior. +Sometimes, a deprecation was not possible, and we would make an outright API +breaking change. + +We'll continue to *introduce* deprecations in major and minor releases (e.g. +1.0.0, 1.1.0, ...). Those deprecations will be *enforced* in the next major +release. + +Note that *behavior changes* and *API breaking changes* are not identical. If we +consider a behavior to be a bug, and fixing that bug induces a behavior change, +we'll release that change in a minor release. This is a sometimes difficult +judgment call that we'll do our best on. + +This doesn't mean that pandas' pace of development will slow down. In the `2019 +Pandas User Survey`_, about 95% of the respondents said they considered pandas +"stable enough". This indicates there's an appetite for new features, even if it +comes at the cost of break API. The difference is that now API breaking changes +will be accompanied with a bump in the major version number (e.g. pandas 1.5.1 +-> 2.0.0). + +See :ref:`policies.version` for more. + +.. _2019 Pandas User Survey: http://dev.pandas.io/pandas-blog/2019-pandas-user-survey.html +.. _SemVer: https://semver.org .. warning:: From 0e9c33ada7dfebc6a218739bec23641c1eaba9e7 Mon Sep 17 00:00:00 2001 From: Tom Augspurger Date: Thu, 12 Sep 2019 14:19:01 -0500 Subject: [PATCH 2/7] semver --- doc/source/development/policies.rst | 3 +++ 1 file changed, 3 insertions(+) diff --git a/doc/source/development/policies.rst b/doc/source/development/policies.rst index b9d310c841306..022523c9cbbc5 100644 --- a/doc/source/development/policies.rst +++ b/doc/source/development/policies.rst @@ -38,3 +38,6 @@ Deprecations will only be enforced in **major** releases. API-breaking change is a judgement call. We'll do our best, and we invite you to participate in development discussion on the issue tracker or mailing list. + + +.. _SemVer: https://semver.org From f346b4385f82bba163b0c5fa8e1bc6bca3ae1ddb Mon Sep 17 00:00:00 2001 From: Tom Augspurger Date: Thu, 12 Sep 2019 16:00:44 -0500 Subject: [PATCH 3/7] note on experimental --- doc/source/development/policies.rst | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/doc/source/development/policies.rst b/doc/source/development/policies.rst index 022523c9cbbc5..701e0cfc76dfa 100644 --- a/doc/source/development/policies.rst +++ b/doc/source/development/policies.rst @@ -17,7 +17,7 @@ A pandas release number is made up of ``MAJOR.MINOR.PATCH``. API breaking changes should only occur in **major** releases. Theses changes will be documented, with clear guidance on what is changing, why it's changing, and how to migrate existing code to the -new beahvior. +new behavior. Whenever possible, a deprecation path will be provided rather than an outright breaking change. @@ -39,5 +39,7 @@ Deprecations will only be enforced in **major** releases. invite you to participate in development discussion on the issue tracker or mailing list. +These policies do not apply to features marked as **experimental** in the documentation. +Pandas may change the behavior of experimental features at any time. .. _SemVer: https://semver.org From 119fffc016e0cd22007376540567aad876fb5eed Mon Sep 17 00:00:00 2001 From: Tom Augspurger Date: Fri, 13 Sep 2019 10:15:58 -0500 Subject: [PATCH 4/7] updates --- doc/source/development/policies.rst | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/doc/source/development/policies.rst b/doc/source/development/policies.rst index 701e0cfc76dfa..77076173316b1 100644 --- a/doc/source/development/policies.rst +++ b/doc/source/development/policies.rst @@ -21,7 +21,7 @@ new behavior. Whenever possible, a deprecation path will be provided rather than an outright breaking change. -Pandas will introduce deprecations in **major** or **minor** releases. These deprecations will +Pandas will introduce deprecations in **minor** releases. These deprecations will preserve the existing behavior while emitting a warning that provide guidance * How to achieve similar behavior if an alternative is available @@ -42,4 +42,10 @@ Deprecations will only be enforced in **major** releases. These policies do not apply to features marked as **experimental** in the documentation. Pandas may change the behavior of experimental features at any time. +Python Support +~~~~~~~~~~~~~~ + +Pandas will only drop support for specific Python versions (e.g. 3.5.x, 3.6.x) in +pandas **major** releases. + .. _SemVer: https://semver.org From 365801b177078b41e80b8cbddcd54bbb8857210a Mon Sep 17 00:00:00 2001 From: Tom Augspurger Date: Sat, 14 Sep 2019 06:16:54 -0500 Subject: [PATCH 5/7] awkward --- doc/source/development/policies.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/source/development/policies.rst b/doc/source/development/policies.rst index 77076173316b1..cde8f0010bc1e 100644 --- a/doc/source/development/policies.rst +++ b/doc/source/development/policies.rst @@ -11,7 +11,7 @@ Version Policy .. versionchanged:: 1.0.0 -Pandas uses a version of `SemVer`_ to govern deprecations, API compatibility, and version numbering. +Pandas uses a variant of `SemVer`_ to govern deprecations, API compatibility, and version numbering. A pandas release number is made up of ``MAJOR.MINOR.PATCH``. From aa932cbf5db9c5927f65b0d7459adc71f9f71308 Mon Sep 17 00:00:00 2001 From: Tom Augspurger Date: Thu, 19 Sep 2019 08:39:04 -0500 Subject: [PATCH 6/7] updates --- doc/source/development/policies.rst | 22 ++++++++++++++-------- 1 file changed, 14 insertions(+), 8 deletions(-) diff --git a/doc/source/development/policies.rst b/doc/source/development/policies.rst index cde8f0010bc1e..2083a30af09c3 100644 --- a/doc/source/development/policies.rst +++ b/doc/source/development/policies.rst @@ -11,25 +11,31 @@ Version Policy .. versionchanged:: 1.0.0 -Pandas uses a variant of `SemVer`_ to govern deprecations, API compatibility, and version numbering. +Pandas uses a loose variant of semantic versioning (`SemVer`_) to govern +deprecations, API compatibility, and version numbering. A pandas release number is made up of ``MAJOR.MINOR.PATCH``. -API breaking changes should only occur in **major** releases. Theses changes will be documented, -with clear guidance on what is changing, why it's changing, and how to migrate existing code to the -new behavior. +API breaking changes should only occur in **major** releases. Theses changes +will be documented, with clear guidance on what is changing, why it's changing, +and how to migrate existing code to the new behavior. -Whenever possible, a deprecation path will be provided rather than an outright breaking change. +Whenever possible, a deprecation path will be provided rather than an outright +breaking change. -Pandas will introduce deprecations in **minor** releases. These deprecations will -preserve the existing behavior while emitting a warning that provide guidance +Pandas will introduce deprecations in **minor** releases. These deprecations +will preserve the existing behavior while emitting a warning that provide +guidance on: * How to achieve similar behavior if an alternative is available * The pandas version in which the deprecation will be enforced. We will not introduce new deprecations in patch releases. -Deprecations will only be enforced in **major** releases. +Deprecations will only be enforced in **major** releases. For example, if a +behavior is deprecated in pandas 1.2.0, it will continue to work, with a +warning, for all releases in the 1.x series. The behavior will change and the +deprecation removed in the next next major release (2.0.0). .. note:: From 13393302b46ad481491b66a315e800e5feecda91 Mon Sep 17 00:00:00 2001 From: Tom Augspurger Date: Thu, 19 Sep 2019 08:56:43 -0500 Subject: [PATCH 7/7] fixup --- doc/source/whatsnew/v1.0.0.rst | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/doc/source/whatsnew/v1.0.0.rst b/doc/source/whatsnew/v1.0.0.rst index 7f0083f00b73a..f60b8085de3d1 100644 --- a/doc/source/whatsnew/v1.0.0.rst +++ b/doc/source/whatsnew/v1.0.0.rst @@ -19,10 +19,11 @@ We'll continue to *introduce* deprecations in major and minor releases (e.g. 1.0.0, 1.1.0, ...). Those deprecations will be *enforced* in the next major release. -Note that *behavior changes* and *API breaking changes* are not identical. If we -consider a behavior to be a bug, and fixing that bug induces a behavior change, -we'll release that change in a minor release. This is a sometimes difficult -judgment call that we'll do our best on. +Note that *behavior changes* and *API breaking changes* are not identical. API +breaking changes will only be released in major versions. If we consider a +behavior to be a bug, and fixing that bug induces a behavior change, we'll +release that change in a minor release. This is a sometimes difficult judgment +call that we'll do our best on. This doesn't mean that pandas' pace of development will slow down. In the `2019 Pandas User Survey`_, about 95% of the respondents said they considered pandas