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..2083a30af09c3 --- /dev/null +++ b/doc/source/development/policies.rst @@ -0,0 +1,57 @@ +.. _develop.policies: + +******** +Policies +******** + +.. _policies.version: + +Version Policy +~~~~~~~~~~~~~~ + +.. versionchanged:: 1.0.0 + +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. + +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 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. 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:: + + 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. + +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 diff --git a/doc/source/whatsnew/v1.0.0.rst b/doc/source/whatsnew/v1.0.0.rst index a5af4e727391a..f60b8085de3d1 100644 --- a/doc/source/whatsnew/v1.0.0.rst +++ b/doc/source/whatsnew/v1.0.0.rst @@ -3,10 +3,39 @@ 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. 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 +"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::