Best practise process of deprecating code
There are many ways to handle deprecated code, the following describes how we would like to implement this in pandapower.
If existing pandapower functionality should be improved which may damage applications of users, deprecation warning should be implemented to notify the user to update the usage of pandapower. Deprecation warnings should exist from one minor version release (at least) until the next major or minor version release. When announcing pandapower functionality changes, always provide the new desired functionality instantly.
This figure illustrates a time sequence of a process with deprecation warnings, assuming that the need for revision has been determined and implemented at pandapower version v2.10.0.
Proposed steps for contributers and reviewers:
- Provide two pull requests (PR1 and PR2) including
- final code that should remain in the long-term
if input parameter names have been changed, these can be catched and notified using
raise DeprecationWarning("Notification message")
- interim code to be contained in the master branch from the next to the next but one release version
to implement deprecation warnings type
warnings.warn("Notification message", category=DeprecationWarning)(
category=FutureWarningis also possible; don’t forget
the new functionality should be available but if the user does not pass arguments that explicitely call the new functionality, the old functionality should be evaluated plus sending DeprecationWarnings
make sure to add new tests for the new functionality
assert Version(pp.__version__) < Version('2.12')with
from packaging.version import Versionto the tests of the deprecated functionality (assuming that the latest pandapower version is v2.10.x ; tests of the deprecated code should be removed with PR1)
Reviewer: don’t approve the PRs as long as both PRs are correct and complete
The person merging PR2 is responsible to merge PR1 after the next release
As an example, please have a look at the revision of the function pandapower.toolbox.merge_nets(). It has been revised by PR2 temporarly. This state is available from pandapower version v2.10.0 to v2.11.1. With v2.12.0 the final code, merged via PR1, is available.
For suggestions on revising this process, Issue 1760 can be reopened.