Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Added version policy #28415

Merged
merged 10 commits into from
Sep 20, 2019
Merged

Added version policy #28415

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
10 commits
Select commit Hold shift + click to select a range
dd57c71
Added version policy
TomAugspurger Sep 12, 2019
0e9c33a
semver
TomAugspurger Sep 12, 2019
f346b43
note on experimental
TomAugspurger Sep 12, 2019
9cd3236
Merge remote-tracking branch 'upstream/master' into version-policy
TomAugspurger Sep 13, 2019
119fffc
updates
TomAugspurger Sep 13, 2019
00a179b
Merge remote-tracking branch 'upstream/master' into version-policy
TomAugspurger Sep 14, 2019
365801b
awkward
TomAugspurger Sep 14, 2019
714dc3d
Merge remote-tracking branch 'upstream/master' into version-policy
TomAugspurger Sep 19, 2019
aa932cb
updates
TomAugspurger Sep 19, 2019
1339330
fixup
TomAugspurger Sep 19, 2019
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions doc/source/development/index.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,4 +16,5 @@ Development
internals
extending
developer
policies
roadmap
40 changes: 40 additions & 0 deletions doc/source/development/policies.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

"version" -> "variant"? "version of SemVer" seems awkward


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.
simonjayhawkins marked this conversation as resolved.
Show resolved Hide resolved

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
TomAugspurger marked this conversation as resolved.
Show resolved Hide resolved
preserve the existing behavior while emitting a warning that provide guidance
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

may be a colon at the end?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
preserve the existing behavior while emitting a warning that provide guidance
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.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Would be good to mention that major releases will happen at the team's discretion, unless we had talked yesterday about a cadence of major release.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If we merge a breaking change to master, then the next release is a major release? or do we have to maintain two branches.

2 branches would avoid cramming the work involved in actually executing deprecations between the final minor release and the next major release.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If we merge a breaking change to master, then the next release is a major release? or do we have to maintain two branches.

In practice it will go the other way around: we discuss if we want to make a major release, and then merge or not ;)

But it's certainly something we should think about how feasible it is. If we want to do bigger breaking changes (eg enabling nullable integers as default), even though we might already have it optional, we will need some time that those can sit in master. So the question will then be if we still want to further develop a stable branch, or only do bug fixes for that.
(now, I am not sure we need/can discuss this in detail now without having it in practice, but in general it is certainly a point to take into consideration)

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This can maybe use a bit more explanation (I am not sure everybody reads "enforced" the same, I am myself sometimes confused about this terminolog). Attempt:

... This means that a deprecated behaviour which is introduced in a minor release (eg 1.2) will continue to work for other minor releases in that series (other 1.x releases), but raise a warning. The deprecation will then only be removed and the behaviour changed in the next major release.


.. note::

Pandas will sometimes make *behavior changing* bug fixes, as part of
TomAugspurger marked this conversation as resolved.
Show resolved Hide resolved
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.
36 changes: 32 additions & 4 deletions doc/source/whatsnew/v1.0.0.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 <https://pandas.pydata.org/pandas-docs/version/0.24/install.html#install-dropping-27>`_ 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
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

First note here that API breaking changes will only happen in major releases? (as that part of the policy is actually not explicitly mentioned here)

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

"here" being this section, or this document?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think it could be literally here (before the sentence that I commented on), but in the end it is mainly important it is mentioned in this document, if you see a better order.

So the comment is basically that the part of "breaking changes will only happen in major releases" (which is explained in the policies.rst document) is not explicitly mentioned in the whatsnew note.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Whoops, I was confused by the diff. Thought we were still in policies.st.

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::

Expand Down