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.

../_images/deprecating.svg

Proposed steps for contributors and reviewers:

  1. Provide two pull requests (PR1 and PR2) including
    1. final code that should remain in the long-term

      • if input parameter names have been changed, this can be handled and a notification issued using raise DeprecationWarning("Notification message")

    2. 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=FutureWarning is also possible; don’t forget import warnings)

      • the new functionality should be available but if the user does not pass arguments that explicitly call the new functionality, the old functionality should be evaluated plus sending DeprecationWarnings

      • make sure to add new tests for the new functionality

      • please add assert Version(pp.__version__) < Version('2.12') with from packaging.version import Version to 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)

  2. Reviewer: don’t approve the PRs as long as both PRs are correct and complete

  3. 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 temporarily. 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.