Last updated at 11:07 pm UTC on 31 January 2019
As of the 3.6 release, Squeak now has a mechanism for officially deprecating methods which need to be removed.
The purpose of deprecating a method rather than simply removing it, is to allow a period of time when code which depends on the deprecated method will still run, but will pop up warnings if you have the #showDeprecationWarnings preference turned on.
This is especially important when a method in a fundamental Squeak class needs to be removed, as many other applications/packages may depend on the existence of that method. Declaring the method as deprecated for some time (e.g. for at least one or two Squeak releases) will give the package developer some time to update his or her package before the package hits an error, due to the method disappearing. – Doug Way
Deprecations for Squeak 6.0a
New deprecations go into '60Deprecated'.
Only use #deprecated or #deprecated: and move it into '60Deprecated' AFTER you removed all senders in the image to it. For example this is not yet the case for #setBalloonText: and #setBalloonText:maxLineLength:. That's why they are simple #flag: sends for now.
Also note that Squeak 6.0a later became Squeak 5.2a.
To deprecate a method, insert "self deprecated: '(explanation)'." as the first line of the method, and leave the rest of the method intact. The string explanation should explain what the sender should do instead of calling this old method. For example:
"My old method which I'm now deprecating."
| x |
self deprecated: 'Use GeeClass>>fooMethod: instead.'.
x := arg1 + 13.
... (original code continues here...)
(Alternatively, you could replace the original code (following the deprecate: line) in your method with a direct call to the replacement method, if the original code no longer works anyway.)
There is also a method #deprecated:block: which can be used instead, although #deprecated: is usually preferred and works in almost all cases.
Deprecating classes is not quite as simple, but the current thinking is that you should do this:
And at least one of:
- Insert "This class is deprecated. Use xxx class or the yyy package classes instead." as the first line of the class comment.
- Implement #basicNew on the class side like this:
self deprecated: 'This class is deprecated. Use xxx class or the yyy package instead.'.
^ super basicNew
- Move the class into a class category called "Deprecated" (if #basicNew causes too many problems).
See this discussion on squeak-dev for more background.
Finding and cleaning up deprecated code and references
To see if any deprecated methods are being used in your image during runtime, turn on the #showDeprecationWarnings preference ( Evaluate "Preferences enable: #showDeprecationWarnings"). (This may bring up deprecation warnings other than the ones that you're interested in (for example the ones that your package calls). To get rid of the other warnings, you may want to temporarily comment out the other deprecation: calls as they come up in the Debugger.) To get rid of all warnings evaluate "Preferences disable: #showDeprecationWarnings."
Generally, you should not have the #showDeprecationWarnings preference turned on unless you are working on cleaning up references to deprecated methods, or working in an alpha release image in which you wouldn't mind doing some cleaning.
To list all of the deprecated methods in the image, simply browse the senders of #deprecated and #deprecated:block:.
In the official Squeak release image, any methods which are deprecated during one release (say, during 3.8alpha) will not be removed from the system until the following release (3.9alpha) at the earliest. That way, a package which depends on the deprecated method will see warnings in the 3.8 release but will still work, and will not have a problem until the 3.9 release.
If the deprecated methods were core methods with widespread usage, they might not be removed for 2 or 3 releases, at the discretion of The Harvesters.