On Sat, Jan 25, 2014 at 8:29 AM, Ezio Melotti <ezio.melo...@gmail.com>wrote:
> Hi, > a couple of years ago I suggested to define and document our > deprecation policy in this thread: > https://mail.python.org/pipermail/python-dev/2011-October/114199.html > I didn't receive many replies and eventually nothing was done. > Lately the same issue came up on #python-dev and Larry and Nick > suggested me to bring this up again. Nick also suggested to document > our deprecation policy in PEP 5 (Guidelines for Language Evolution: > http://www.python.org/dev/peps/pep-0005/ ). > > I'm including below the full text of the original email. > > Best Regards, > Ezio Melotti > > ------------------------------- > > Hi, > our current deprecation policy is not so well defined (see e.g. [0]), > and it seems to me that it's something like: > 1) deprecate something and add a DeprecationWarning; > 2) forget about it after a while; > 3) wait a few versions until someone notices it; > 4) actually remove it; > > I suggest to follow the following process: > 1) deprecate something and add a DeprecationWarning; > 2) decide how long the deprecation should last; > 3) use the deprecated-remove[1] directive to document it; > 4) add a test that fails after the update so that we remember to remove > it[2]; > > Other related issues: > > PendingDeprecationWarnings: > * AFAIK the difference between PDW and DW is that PDW are silenced by > default; > * now DW are silence by default too, so there are no differences; > * I therefore suggest we stop using it, but we can leave it around[3] > (other projects might be using it for something different); > > Deprecation Progression: > Before, we more or less used to deprecated in release X and remove in > X+1, or add a PDW in X, DW in X+1, and remove it in X+2. > I suggest we drop this scheme and just use DW until X+N, where N is > >=1 and depends on what is being removed. We can decide to leave the > DW for 2-3 versions before removing something widely used, or just > deprecate in X and remove in X+1 for things that are less used. > The way I used PendingDeprecationWarning is that it is used until two releases before removal. If we want to add a keyword-only parameter to DeprecationWarning which specifies when the feature will be removed then PendingDeprecationWarning is really not needed; 'removal' maybe? Could then come up with a template format that's consistent when 'removal' is specified: '{} is deprecated and slated for removal in {} {}'.format(str(self.args), self.project, self.removal) # self.project defaults to 'Python'. Depending on how fancy we get we could have it so that when you warn on a DeprecationWarning where 'removal' equals sys.version (or whatever) then it always turns into an error case and thus raised as an exception. -Brett > > Porting from 2.x to 3.x: > Some people will update directly from 2.7 to 3.2 or even later > versions (3.3, 3.4, ...), without going through earlier 3.x versions. > If something is deprecated on 3.2 but not in 2.7 and then is removed > in 3.3, people updating from 2.7 to 3.3 won't see any warning, and > this will make the porting even more difficult. > I suggest that: > * nothing that is available and not deprecated in 2.7, will be > removed until 3.x (x needs to be defined); > * possibly we start backporting warnings to 2.7 so that they are > visible while running with -3; > > Documenting the deprecations: > In order to advertise the deprecations, they should be documented: > * in their doc, using the deprecated-removed directive (and possibly > not the 'deprecated' one); > * in the what's new, possibly listing everything that is currently > deprecated, and when it will be removed; > Django seems to do something similar[4]. > (Another thing I would like is a different rending for deprecated > functions. Some part of the docs have a deprecation warning on the > top of the section and the single functions look normal if you miss > that. Also while linking to a deprecated function it would be nice to > have it rendered with a different color or something similar.) > > Testing the deprecations: > Tests that fail when a new release is made and the version number is > bumped should be added to make sure we don't forget to remove it. > The test should have a related issue with a patch to remove the > deprecated function and the test. > Setting the priority of the issue to release blocker or deferred > blocker can be done in addition/instead, but that works well only when > N == 1 (the priority could be updated for every release though). > The tests could be marked with an expected failure to give some time > after the release to remove them. > All the deprecation-related tests might be added to the same file, or > left in the test file of their module. > > Where to add this: > Once we agree about the process we should write it down somewhere. > Possible candidates are: > * PEP387: Backwards Compatibility Policy[5] (it has a few lines about > this); > * a new PEP; > * the devguide; > I think having it in a PEP would be good, the devguide can then link to it. > > > Best Regards, > Ezio Melotti > > > [0]: http://bugs.python.org/issue13248 > [1]: deprecated-removed doesn't seem to be documented in the > documenting doc, but it was added here: > http://hg.python.org/cpython/rev/03296316a892 > [2]: see e.g. > http://hg.python.org/cpython/file/default/Lib/unittest/test/test_case.py#l1187 > [3]: we could also introduce a MetaDeprecationWarning and make > PendingDeprecationWarning inherit from it so that it can be used to > pending-deprecate itself. Once PendingDeprecationWarning is gone, the > MetaDeprecationWarning will become useless and can then be used to > meta-deprecate itself. > [4]: https://docs.djangoproject.com/en/dev/internals/deprecation/ > [5]: http://www.python.org/dev/peps/pep-0387/ > _______________________________________________ > Python-Dev mailing list > Python-Dev@python.org > https://mail.python.org/mailman/listinfo/python-dev > Unsubscribe: > https://mail.python.org/mailman/options/python-dev/brett%40python.org >
_______________________________________________ Python-Dev mailing list Python-Dev@python.org https://mail.python.org/mailman/listinfo/python-dev Unsubscribe: https://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
