Deprecation guide for methods, classes and packages

Hi,

From Bug #20900/ PR 1818 it looked like it is not really clear on how to "deprecate" correctly. Therefore I summarized and
wrote a short guide following what we contributors used as best practice so far. Also read [1], [2] and [3] and check some of the
deprecation settings in the Pharo settings browser. Just open SettingsBrowser and search for "Depre".

I write this mail to "pharo-dev" with CC: "pharo-users" list - because of common interest. But comments and replies should
please go to "pharo-dev" so we do not disrupt the thread too much. Thanks!

Please review what I wrote and ideally we can put the text or a link to it as "Deprecation guide" into the documentation
 / wiki / ... on GitHub afterwards.

Hope this helps a little bit.

Thanks
T.

[1] https://en.wikipedia.org/wiki/Deprecation
[2] https://www.peteruhnak.com/blog/2015/08/06/transforming-deprecated-code-with-rewritetool/
[3] https://pharoweekly.wordpress.com/2016/06/17/automatic-deprecation-refactoring/

------------------------------------------------------------------------------------------------------------------------------
In any Pharo version we have a special package hosting deprecated methods and classes. This allows smooth migration for Pharo users
as code should still load and runs to some extent - but deprecation warnings and possibly a helping hand (in form of automatic
code transformations) could be given to support migration.

As we currently work on Pharo7 there is a "Deprecated70" package in the image hosting deprecated methods and classes intended to be
removed for Pharo 8. When Pharo 7 is released the users can easily spot the deprecations - also because they are striked through
(more on this below). When Pharo 8 iteration starts the "Deprecated70" will be replaced with an empty "Deprecated80" package.


DEPRECATING METHODS
===================  

   If you deprecate a METHOD use #deprecated: message and switch it to be an extension method in *Deprecated70*. If the
   method could be replaced by calling another method then dispatch the call to the new method and ideally provide a transformation
   so next time the old method is called the sender method is automagically rewritten and could be adopted/migrated:

        oldMethod
        "An old method we do not use anymore. But luckily there is a replacement."

            self deprecated: 'Please use #newMethod instead'
              transformWith: '`@receiver oldMethod' -> '`@receiver newMethod'.

            ^ self newMethod

    So if there is a method like

       foo
  self oldMethod

    sending the old deprecated method it will be migrated to

       foo
  self newMethod

    as soon as foo, the oldMethod and the transformation is called. If the automatically migrated method is under version
    control (Monticello or git) you will easily see that #foo was modified.

    In case there is no replacement for a method you would like to deprecate then it is best to throw an error when it is used:

        veryOldMethod
           "A very old method hopefully nobody uses. So we do no provide a replacement."

            self deprecated: 'The method #veryOldMethod is deprecated without any replacement'.

           ^ self error: 'Do not use #veryOldMethod anymore'

    Note that the method is striked through in the Pharo system browser in both cases to show that it should not be used anymore.

    In the standard image calling a deprecated method is logged on the Transcript and flagged with a warning dialog. This should
    help users and maintainers of external packages to easily spot when they still use deprecated code.
    You can change these settings in Pharo Settings Browser under Tools -> Debugging -> Deprecation Handling.

DEPRECATING CLASSES
===================

   If you deprecate a CLASS implement #isDeprecated on class side to return true and move it to package "Deprecated70"
   Ideally write in the class comment why it is deprecated and if there is a replacement class what to use instead

        Object subclass: #OldClass
                instanceVariableNames: ''
                classVariableNames: ''
                package: 'Deprecated70-OldTag'

    and comment to explain the reasons:

         OldClass comment: 'Use NewClass instead'.  

    and implement in class side method category 'testing'  
     
       isDeprecated
          "We do not need this class anymore"
     ^true

    Note that the class is striked through in the system browser.


DEPRECATING PACKAGES
====================

   If you deprecate a PACKAGE then rename it with "Deprecated" in the name. Let the class side of the package manifest
   (typically a subclass of PackageManifest within the package) als return #isDeprecated with true. In the class
   comment of the package manifest (which also serves as package comment) explain why the package is deprecated and
   if there is a replacement or not.
   
   Example: your package name is "OldPackage-Core", so the new name is "OldPackage-Deprecated-Core". Create a manifest
            or use the existing one. A Manifest should be a subclass of PackageManifest and should be categorized within
            a 'Manifest' tag.

        PackageManifest subclass: #ManifestOldPackageCore
         instanceVariableNames: ''
            classVariableNames: ''
            package: 'OldPackage-Deprecated-Core-Manifest'

    and comment to explain the reasons:

        ManifestOldPackageCore comment: 'This package is not useful anymore. Check NewPackage for replacement'.

    and implement in class side method category 'testing'  
     
       isDeprecated
          "We do not need this package anymore"
     ^true

    Note that the manifest class and the package is striked through in the system browser. Be aware that a deprecated
    package might be removed completely already in the next Pharo major version iteration.

Torsten, this is extremely helpful, thank you.

There's a new commit for PR 1818. I'd appreciate any additional feedback.



--
Sent from: http://forum.world.st/Pharo-Smalltalk-Users-f1310670.html