Introduce a helper function for deprecation

[pradyunsg]

Built on top of #5523

Replaces the current deprecation setup with one which has a single function -- the new deprecated function also includes 3 optional parameters:

• Issue number: that gets converted into a URL (to guide users to a dedicated issue if needed)
• Replacement: Provide a way to suggest alternatives to the functionality deprecated.
• Gone In: Specifies which version of pip the functionality would be removed in.

Providing these should make it easier for users to reach places with more context and also make it more explicit that users need to be provided advice about how to deal with the deprecation.

[dstufft]

One thing I don't like about this, is it removes the note about when a particular deprecation can be removed. I think that's important because otherwise we'll end up with stuff that has been marked deprecated for ages that we've just forgotten exists. Now that we have date based releases, it should be pretty easy to handle this though (easier than the old way), just set the version it's going to be removed in, and once we're at that version, raise exceptions instead of warnings so that our tests break and force us to remove them.

[pradyunsg]

I wasn't sure how the logic should behave if we skipped a release for the year. Say something had to go away in 19.3 but we skipped 19.2 in the first release month for it so, it came 3 months later. How should the deprecation warnings/errors behave (19.3 could also be 20.1 or something instead)?

[dstufft]

I wouldn't skip version numbers, if 19.2 is the next version, it should be the next version, unless we roll over to the next year. However, maybe the better thing to do is instead of making the deprecation policy release based, we make it time based as well. We can say that our policy is items will emit deprecation warnings for at least 6 months (so that's 2 releases worth of deprecation warnings).

You can then just do a >= check on the release, version. For instance:

Jan - 19.0 - Thing #1 gets Deprecated, mark as remove in >= 19.2
Apr - 19.1
Jul - 19.2 - This release gets skipped for reasons
Oct - 19.2 - This is >= 19.2, so we remove Thing #1, it was left for 9mo instead of 6mo, but that's OK.

Or another scenario:

Jan - 19.0 - Thing #1 gets Deprecated, mark as remove in >= 19.2
Apr - 19.1
Jul - 19.2 - This release gets skipped for reasons
Oct - 19.2 - This release also gets skipped for reasons.
Jan - 20.0 - 20.0 is >= 19.2, so Thing #1 gets removed.

[dstufft]

#5572 has some recommended language to adjust the deprecation policy by.

[pradyunsg]

I don't think there's much to gain from preserving the current logger.warning -> logger.error progression. Does anyone mind if I remove that? If so, please let me know what logic you'd want to apply for deciding between which method to use.

[dstufft]

I'm fine with getting rid of it.

[pradyunsg]

Cool. This should work.

---

PS: GitHub did a good job at suggesting people to request a review from. :)

[dstufft]

One thing I'd like to add to this, is a little bit of documentation in the deprecation policy area about how to use this function, and what values should be passed into this.

[BrownTruck]

Hello!

I am an automated bot and I have noticed that this pull request is not currently able to be merged. If you are able to either merge the master branch into this pull request or rebase this pull request against master then it will eligible for code review and hopefully merging!

[BrownTruck]

Hello!

I am an automated bot and I have noticed that this pull request is not currently able to be merged. If you are able to either merge the master branch into this pull request or rebase this pull request against master then it will eligible for code review and hopefully merging!

[pradyunsg]

I noticed @BrownTruck -- was running tests locally after a rebase to make sure I did it correctly.

(why am I talking to a bot)

[pradyunsg]

@dstufft Anything else?

[lock]

This thread has been automatically locked since there has not been any recent activity after it was closed. Please open a new issue for related bugs.