Deprecation policy

[fafhrd91]

we need some formal way to deprecate api/features/etc.

my suggestion, lets create DEPRECATIONS.txt, and whenever we add deprecation warning to code, we add entry to this file with links to code, reasons, and removal date.

[fafhrd91]

@asvetlov @kxepal @popravich @jettify

[kxepal]

@fafhrd91
I fear it will make too complicated procedure of understanding what to expect in a new release since unlikely people will read DEPRECATIONS.txt or else file after CHANGES.txt.

How about to pick keepchangelog way and describe all the things in a CHANGES.txt as more verbose as they deserve? Having one single place that describes all the changes, deprecations, migrations and mitigations for a specific release is a good idea.

[fafhrd91]

this file is not for people, it is for us. for example i have no idea when to remove some deprecated api. and we have a lot.

[kxepal]

That sounds like warning.warn('will be removed in X.Y.Z, use method foo() instead. See also #123 on GH', DeprecationWarning) and a related issue here for speciifed milestone would be enough. As a bonus, there would be a place to discuss surrounding problems, compatibility issues and the rest things. Once you decide to cut X.Y.Z. release, you'll have to close those tickets/PRs anyway so you wouldn't miss them and they wouldn't bloat a single text file.

[fafhrd91]

i still prefer one file, which i can just read and not browse gh.
sometimes we can not show deprecation warning, for example cookies back port for python3.4.2

[fafhrd91]

sure we will need to include info to changes about upcoming deprecations and removal of apis. but we can source it from one place.

[kxepal]

Well, it's up to you, I just see DEPRECATIONS.txt as an another source of manual work: you'll have to not forget apply those deprecations in time. The tagged/milestoned issues are better reminders with a little bit more features like discussion and feedback accumulation.

[AlJohri]

Maybe you can automatically generate deprecations.txt from running the test suite and capturing warnings or static code analysis for all deprecation warnings.

[fafhrd91]

we not always have deprecation warnings in-place, sometimes it is set of apis, for example wsgi.

[popravich]

I'm agree with @kxepal — properly tagged issues should work better.
In my opinion DEPRECATIONS.txt would look like issues filtered by that tag...
Anyway I'm ok with any choice.

[fafhrd91]

i hate open issues.

[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.

If you feel like there's important points made in this discussion,
please include those exceprts into that new issue.