Added version policy
This tries to codify the discussion about versioning from yesterday. I tried to summarize the group's thoughts. Let me know if any of my biases slipped through.

cc @pandas-dev/pandas-core 

@mroeschke brings up a good point in https://github.com/pandas-dev/pandas/pull/28415#discussion_r323862907. What do we want to say about

1. Release cadence
2. Backports

Django is very explicit here: https://www.djangoproject.com/download/#supported-versions. I'm not sure if we're ready to do something like that. But perhaps we can provide some guidance? > Currently we are including some deprecations in 1.0. Ideally, we should try to keep this number limited I think (we should try to deprecate as much as we want in the release before it), as we need to keep them until 2.0.

I was thinking we should remove these. Some friction in the interim but I don't see the long term advantage of introducing deprecated behavior into a major release > I was thinking we should remove these. Some friction in the interim but I don't see the long term advantage of introducing deprecated behavior into a major release

Sorry, we actually have none yet: https://dev.pandas.io/whatsnew/v1.0.0.html#deprecations. I was mixing it up with api breakages (which are mostly very minor up to now). Should python version support be linked to major releases? i.e if 1.0.0 is released with py3.5 support, it won't be dropped to 2.0.0.

or if we adopt #27557, then python versions can be dropped in minor releases . 

do we need to be clear and include python support in this policy? I wouldn't mind adopting a _release_ schedule similar to Django (e.g. release minor versions every 6 months, release major version every year). Keeps things simple, predictable, and accountable no matter where we are at the current development stage. At minimum, there should probably be deprecations over a year that could constitute a major bump.

Backport and LTS support probably needs more discussion.  > do we need to be clear and include python support in this policy?

I think a statement on that is appropriate for this document. Are people on board with following NumPy's policy? If so, let's add that as a section here, and link to the NEP (once it's merged). > > do we need to be clear and include python support in this policy?
>
> I think a statement on that is appropriate for this document. Are people on board with following NumPy's policy? If so, let's add that as a section here, and link to the NEP (once it's merged).

Meaning: not linking it to our major/minor policy, right? As I think Simon's question (at least the rest of his comment) was explicitly about that: can we drop python version support in minor releases? 

(personally I don't think we should link it, it's difficult to exactly predict how things will work out) Yes you do great

Vào 12 Th9, 2019 23:01, Tom Augspurger <notifications@github.com> đã viết:

This tries to codify the discussion about versioning from yesterday. I tried to summarize the group's thoughts. Let me know if any of my biases slipped through.

cc @pandas-dev/pandas-core<https://github.com/orgs/pandas-dev/teams/pandas-core>

________________________________
You can view, comment on, or merge this pull request online at:

  https://github.com/pandas-dev/pandas/pull/28415

Commit Summary

  *   Added version policy

File Changes

  *   M doc/source/development/index.rst<https://github.com/pandas-dev/pandas/pull/28415/files#diff-0> (1)
  *   A doc/source/development/policies.rst<https://github.com/pandas-dev/pandas/pull/28415/files#diff-1> (40)
  *   M doc/source/whatsnew/v1.0.0.rst<https://github.com/pandas-dev/pandas/pull/28415/files#diff-2> (36)

Patch Links:

  *   https://github.com/pandas-dev/pandas/pull/28415.patch
  *   https://github.com/pandas-dev/pandas/pull/28415.diff

—
You are receiving this because you are subscribed to this thread.
Reply to this email directly, view it on GitHub<https://github.com/pandas-dev/pandas/pull/28415?email_source=notifications&email_token=AJLD4SOIM6SH6RBE3H4NS23QJJRWDA5CNFSM4IWGQQVKYY3PNVWWK3TUL52HS4DFUVEXG43VMWVGG33NNVSW45C7NFSM4HLBAFAA>, or mute the thread<https://github.com/notifications/unsubscribe-auth/AJLD4SPXPYR7TL5FF4BS6YTQJJRWDANCNFSM4IWGQQVA>.

 Outstanding discussion items:

1. Do we introduce deprecations in X.0.0?:
https://github.com/pandas-dev/pandas/pull/28415#discussion_r323850666
  - Right now the preference seems to be no deprecations in X.0.0.
  - May be a bit hard though, depending on the time between releases.
2. Guidance on release cadence? How long will be do backports for? Will we have LTS branches?
  - Hard to say without trying it.
  - I suspect the pace of releases will be similar to what they are now.
3. When might we drop support for a Python? Major only? Major or minor?
  - Link to the NEP? > Outstanding discussion items:
> 
> 1. Do we introduce deprecations in X.0.0?:
>    [#28415 (comment)](https://github.com/pandas-dev/pandas/pull/28415#discussion_r323850666)
> 
> * Right now the preference seems to be no deprecations in X.0.0.
> * May be a bit hard though, depending on the time between releases.

I don't see why we wouldn't include new deprecations in s major release, so -1 on say we don't.


> 
> 1. Guidance on release cadence? How long will be do backports for? Will we have LTS branches?
> 
> * Hard to say without trying it.
> * I suspect the pace of releases will be similar to what they are now.

I would provide no guarantees.

no LTS at all (w/o separately guaranteed funding).

> 
> 1. When might we drop support for a Python? Major only? Major or minor?
> 
> * Link to the NEP?

 Agree with Jeff.

For dropping Python support, to me it makes more sense to drop it only in major releases, since it's easier to communicate (and for users to remember and be aware). But not a big deal if it makes our lives more difficult. And I'd like the NEP (we can say we will follow when it makes sense, if we anticipate we may need to be flexible). Roughly speaking, how often do people think we'll do major releases? In my head, I've been thinking approximately yearly. > Roughly speaking, how often do people think we'll do major releases? In my head, I've been thinking approximately yearly.

In my head, I think it will rather be something like 2 (or 3) yearly. 

If you look at the last years, we had the following minor releases:

* 0.25: July 2019
* 0.24: January 2019
* 0.23: May 2018
* 0.21/0.22: October / December 2017 (counting as one with the empty sum change)
* 0.20: May 2017
* 0.19: October 2016
* 0.18: March 2016

so we had at most 2 minor releases a year. And personally, I think it is certainly reasonable to do 3 to 4 minor releases before another major release (which gives easily 2 years with the current release cycle). 
We might of course also want to try speed up the release cycle, though. OK, I think we're pretty close here. We don't have

1. a schedule / guidance on how often we'll release major / minor versions.
2. Guidance on how long (if at all) we'll make backports to the previous major branch.

It's a bit hard to give guidance on those right now. Let's leave this open for a few more days? (I don't think there is any hurry to get this merged quickly) 
I just notified the mailing list that the discussion continued here. 
 > a schedule / guidance on how often we'll release major / minor versions.

I think it is fine for now to not have this, as it is very difficult to predict how it will go. Certainly for major releases, I suppose for minor releases it will be somewhat similar as to how we are doing now? (although we might want to try increase the speed a bit? eg towards 3 instead of 2 minors a year?) 

I am fine with the suggestion of Marc to give a vague idea how it was in the past (2 / year), with the clear remark of volunteer-based, no commitment to exact schedule, etc.  But also fine to leave that out for now.

> Guidance on how long (if at all) we'll make backports to the previous major branch.

IMO, we will need to do *some* form of LTS, when going for this proposal. 
Right now we normally don't do any bug fix release any more to x.y once x.y+1 is out. For minor releases we can certainly continue doing that. But for major release branches, I don't think it would be that uncommon to still do some bug fixes even after the next major release (whether it are just some compatibility fixes with a new python or numpy that is released shortly after the next major release). 
But again, I don't think it is needed to already codify this now in the text. We can see how it goes in practice.




 A few comments having been on the side of delivering commercial software and having these version number discussions:

- I do think it is important to have a commitment to at least one major version a year, because if you end up taking 2 years to do a major version, you have taken a long time to actually deprecate something
- Having said the above, if you decide to do a major release once a year, and there was a minor release 3 months before where there was a deprecation, then when the major release comes, the feature was only deprecated for 3 months.  So you might want to consider that a feature is officially removed when one of the following events occurs *last*:
  - A major release
  - A combination of 3 minor or major releases
  - One year
- You have to decide what constitutes a major vs. minor release.  Is it based on time (e.g., once a year for a major release) or is it based on having a certain set of new features?
- How do you want to handle dependencies on other libraries (numpy, matplotlib, etc.) where they introduce a change that causes something in pandas to break?  So now  you have to deprecate something in pandas because of that dependency.

 @Dr-Irv thanks for the feedback! Some answers / questions

> I do think it is important to have a commitment to at least one major version a year, because if you end up taking 2 years to do a major version, you have taken a long time to actually deprecate something

Currently, we keep a deprecated feature for 3 minor releases (e.g. deprecate in 0.22, also 0.23 & 0.24 get the warning, removed in 0.25). With our current release schedule, this means that deprecations are already kept for a minimum of ca 1.5 years. So extending this to eg 2 years does not seem that of a problem to me. 

Also, for "ideal" deprecations, you can already act upon them to get the new (or keep the old) behaviour, and not see the warning any more. For those cases, I also don't think that it is a problem that a deprecation takes a long time. 
Or can you explain why taking a long time to deprecate something might be a bad thing? (except that it can be a burden to pandas development)

>  there was a minor release 3 months before where there was a deprecation, then when the major release comes, the feature was only deprecated for 3 months. So you might want to consider that a feature is officially removed when one of the following events occurs last: 

(note, this actually also occurs if you would only do a major release every 2 or 3 years) 
What you propose is similar to what django does (if something is deprecated in eg 2.3 and the next release is 3.0, then the feature is only removed in 3.1 instead of 3.0). 
I personally like this, and it was very briefly discussed at the hangout, but for now seemed to add more complexity than needed (if I remember this correctly)

> You have to decide what constitutes a major vs. minor release. Is it based on time (e.g., once a year for a major release) or is it based on having a certain set of new features?

For now, the only thing that we decided is: it is based on having breaking changes (meaning: direct behavioural changes, or removals of deprecations). 
That said, it is my hope that those breaking changes also come with new features (eg switching the default integer dtype to the nullable integer dtype). 

With our current resources, I don't think we can make more concrete commitments ..

> How do you want to handle dependencies on other libraries (numpy, matplotlib, etc.) where they introduce a change that causes something in pandas to break? So now you have to deprecate something in pandas because of that dependency.

Do you have a more concrete example in mind? 
In general, I would say that if there is a change in pandas behaviour due to a change in eg numpy or matplotlib, which is outside of our control (in practice quite some changes in dependencies can be worked around in pandas itself), that should not have influence on our version policy.





 @jorisvandenbossche 

> Or can you explain why taking a long time to deprecate something might be a bad thing? (except that it can be a burden to pandas development)

This is just a personal feeling as a user, but with the current policy of waiting 3 minor releases, and with the period of time over 3 minor releases being close to 2 years, there is sometimes a feeling of "you said it would be deprecated, so when is that happening already?" when you run into the same deprecated feature again and again.  Now, I have to admit I was involved in commercial software that did releases every 4 months or so, so 3 releases would take about a year, so you didn't get that feeling with the commercial software.

> > You have to decide what constitutes a major vs. minor release. Is it based on time (e.g., once a year for a major release) or is it based on having a certain set of new features?

> For now, the only thing that we decided is: it is based on having breaking changes (meaning: direct behavioural changes, or removals of deprecations).
That said, it is my hope that those breaking changes also come with new features (eg switching the default integer dtype to the nullable integer dtype).

If that's the case, I would suggest that you deprecate a feature over 3 releases, whether they are minor or major.  Because you could get to a point where things are stabilized enough that you might have 5 or 6 minor releases between major ones, and then you are deciding to have a major release because of deprecations, and calling a release "major" without some really new features doesn't feel right.  Again, I have some bias here having been in the commercial world.

> > How do you want to handle dependencies on other libraries (numpy, matplotlib, etc.) where they introduce a change that causes something in pandas to break? So now you have to deprecate something in pandas because of that dependency.

> Do you have a more concrete example in mind?

Not really, but in the back of my mind, I recall seeing some changes made in matplotlib that forced a change in the pandas API that calls matplotlib.  So now because of the matplotlib change, you have to deprecate a pandas API.   Or a new numpy version came out and pandas didn't work with it, so the main developers had to do work to make things work with numpy.

One other point - is there a systematic way that the team is tracking when a feature was deprecated, so that you know when it is safe to remove?   Each deprecation should be associated with a new issue for that
deprecation's remove. That issue will be assigned to the milestone it's
being removed it.

On Mon, Sep 16, 2019 at 4:12 PM Irv Lustig <notifications@github.com> wrote:

> @jorisvandenbossche <https://github.com/jorisvandenbossche>
>
> Or can you explain why taking a long time to deprecate something might be
> a bad thing? (except that it can be a burden to pandas development)
>
> This is just a personal feeling as a user, but with the current policy of
> waiting 3 minor releases, and with the period of time over 3 minor releases
> being close to 2 years, there is sometimes a feeling of "you said it would
> be deprecated, so when is that happening already?" when you run into the
> same deprecated feature again and again. Now, I have to admit I was
> involved in commercial software that did releases every 4 months or so, so
> 3 releases would take about a year, so you didn't get that feeling with the
> commercial software.
>
> You have to decide what constitutes a major vs. minor release. Is it based
> on time (e.g., once a year for a major release) or is it based on having a
> certain set of new features?
>
> For now, the only thing that we decided is: it is based on having breaking
> changes (meaning: direct behavioural changes, or removals of deprecations).
> That said, it is my hope that those breaking changes also come with new
> features (eg switching the default integer dtype to the nullable integer
> dtype).
>
> If that's the case, I would suggest that you deprecate a feature over 3
> releases, whether they are minor or major. Because you could get to a point
> where things are stabilized enough that you might have 5 or 6 minor
> releases between major ones, and then you are deciding to have a major
> release because of deprecations, and calling a release "major" without some
> really new features doesn't feel right. Again, I have some bias here having
> been in the commercial world.
>
> How do you want to handle dependencies on other libraries (numpy,
> matplotlib, etc.) where they introduce a change that causes something in
> pandas to break? So now you have to deprecate something in pandas because
> of that dependency.
>
> Do you have a more concrete example in mind?
>
> Not really, but in the back of my mind, I recall seeing some changes made
> in matplotlib that forced a change in the pandas API that calls matplotlib.
> So now because of the matplotlib change, you have to deprecate a pandas
> API. Or a new numpy version came out and pandas didn't work with it, so the
> main developers had to do work to make things work with numpy.
>
> One other point - is there a systematic way that the team is tracking when
> a feature was deprecated, so that you know when it is safe to remove?
>
> —
> You are receiving this because you authored the thread.
> Reply to this email directly, view it on GitHub
> <https://github.com/pandas-dev/pandas/pull/28415?email_source=notifications&email_token=AAKAOIS4FBYRLZXV3XBYP5LQJ7ZDDA5CNFSM4IWGQQVKYY3PNVWWK3TUL52HS4DFVREXG43VMVBW63LNMVXHJKTDN5WW2ZLOORPWSZGOD62RDGA#issuecomment-531960216>,
> or mute the thread
> <https://github.com/notifications/unsubscribe-auth/AAKAOISRMJDUWD7R2KDK33LQJ7ZDDANCNFSM4IWGQQVA>
> .
>
 > Each deprecation should be associated with a new issue for that
deprecation's remove. That issue will be assigned to the milestone it's
being removed it.

Has that been done in the past with consistency?

I know I did some PR's that deprecated behavior, and certainly didn't create an associated issue for the deprecated issue to be removed in the future!

If that hasn't been consistent, you might want to update the "Contributing to pandas" document to indicate that. That's a new (proposed) policy. > Each deprecation should be associated with a new issue for that
deprecation's remove. That issue will be assigned to the milestone it's
being removed it.

@TomAugspurger I am personally not sure this is necessarily better than one issue per major release gathering all things that should be removed for that major release (a single issue keeps the issue number a bit more down, and gives an easy overview of what still needs to be done on this area for a given major release). 
(but anyway, this is not a fundamental discussion for the actual policy ;))

> One other point - is there a systematic way that the team is tracking when a feature was deprecated, so that you know when it is safe to remove?

@Dr-Irv the current way is https://github.com/pandas-dev/pandas/issues/6581/

> there is sometimes a feeling of "you said it would be deprecated, so when is that happening already?" when you run into the same deprecated feature again and again.

My answer here is that in most cases, you should adjust your code to not run into the warning anymore. That's the main point of those warnings, to give you time to adjust instead of directly having the change (of course, there will always be some cases where this is not straightforward) 
If you do that, a long deprecation period is not that much of a problem (from a user's perspective), and actually makes it easier for users that do not upgrade every release.

> If that's the case, I would suggest that you deprecate a feature over 3 releases, whether they are minor or major. 

That brings us back to the rolling deprecations, the alternative that has been discussed (which is certainly a valid alternative). But personally, I find the argument of "a major release for just deprecations is not worth a major release" not *that* important. Of course it would be nice to also have fancy new features (but that is hard to commit to with the current resources), and also, most new features can be introduced in a backwards compatible manner anyway (eg new methods like explode), so we will continue to do them in minor releases.

 Right, I forgot we settled on one issue per major release. 

> On Sep 17, 2019, at 06:48, Joris Van den Bossche <notifications@github.com> wrote:
> 
> Each deprecation should be associated with a new issue for that
> deprecation's remove. That issue will be assigned to the milestone it's
> being removed it.
> 
> @TomAugspurger I am personally not sure this is necessarily better than one issue per major release gathering all things that should be removed for that major release (a single issue keeps the issue number a bit more down, and gives an easy overview of what still needs to be done on this area for a given major release).
> (but anyway, this is not a fundamental discussion for the actual policy ;))
> 
> One other point - is there a systematic way that the team is tracking when a feature was deprecated, so that you know when it is safe to remove?
> 
> @Dr-Irv the current way is #6581
> 
> there is sometimes a feeling of "you said it would be deprecated, so when is that happening already?" when you run into the same deprecated feature again and again.
> 
> My answer here is that in most cases, you should adjust your code to not run into the warning anymore. That's the main point of those warnings, to give you time to adjust instead of directly having the change (of course, there will always be some cases where this is not straightforward)
> If you do that, a long deprecation period is not that much of a problem (from a user's perspective), and actually makes it easier for users that do not upgrade every release.
> 
> If that's the case, I would suggest that you deprecate a feature over 3 releases, whether they are minor or major.
> 
> That brings us back to the rolling deprecations, the alternative that has been discussed (which is certainly a valid alternative). But personally, I find the argument of "a major release for just deprecations is not worth a major release" not that important. Of course it would be nice to also have fancy new features (but that is hard to commit to with the current resources), and also, most new features can be introduced in a backwards compatible manner anyway (eg new methods like explode), so we will continue to do them in minor releases.
> 
> —
> You are receiving this because you were mentioned.
> Reply to this email directly, view it on GitHub, or mute the thread.
 I don't remember if we already settled on one (I was just stating my preference ;)) > That brings us back to the rolling deprecations,

Yep. And on the last dev call there was consensus with this form of semver.

> I don't remember if we already settled on one (I was just stating my preference ;))

:)

---

Planning to merge in 24 hours if there aren't any objections.

 Good to go here? Thanks Tom!