Re: [win32-gui] Re: [perl-win32-gui-hackers] Notes on deprecated features

[Robert M. <rm...@po...>]

Glenn Linderman wrote:
> On approximately 5/16/2006 12:31 PM, came the following characters from 
> the keyboard of Robert May:
>> As you all know I feel that backwards compatibility is important, and 
>> have been striving not break existing scripts when making changes. 
>> However, going forwards some things will have to change, and I thought 
>> it would be worthwhile for me to outline my strategy for deprecating 
>> and then removing/changing functionality.  I would appreciate comments 
>> on the following:
>>
>> (1) When making a change backwards compatibility will be maintained 
>> wherever possible.  When a change in behaviour is desirable (for 
>> example 'use Win32::GUI;' not exporting 360+ Constants) then a release 
>> (in this case 1.04) will issue a 'deprecated' warning stating that 
>> behaviour will change in the future, and explaining what changes 
>> should be made.
> 
> Care should be taken that the message (or the documentation for the 
> message) points the user to how to eliminate the warning, how to fix the 
> behaviour warned about, so that it works warning-free with the current 
> code, and will not encounter known future warnings or errors when the 
> feature is removed.
> 
> I think this is basically what you are saying.

That was what I intended.

>> (2) A subsequent release (depending on the gaps in the release cycle 
>> and the severity of the change this might be the following release - 
>> in this example 1.05) may change behaviour, but will issue a warning 
>> that the behaviour has changed (may die instead depending on the change).
> 
> If old syntax can be retired, that paves the way for being able to die 
> or perpetuate an error message.  It may not always be the case that the 
> old syntax should be retired. "use Win32::GUI;" seems like syntax that 
> should be made to work without warning even once the constants are removed.
> 
> If it is possible to issue the warning, or remind about the removed 
> feature, at the time of attempted use of the removed feature (constants) 
> that would be nice, but I haven't spent time to figure out if that is 
> possible in this case.

I'll give an example of what I expect for the constants stuff.  I 
certainly don't intend to remove 'use Win32::GUI;', but it's behaviour 
will change, and it won't export any constants.

Currently
   use Win32::GUI;
exports over 300 arbitrary constants into the callers name space.  IMHO 
this construct should either export all constants, or none.  Now that 
all constants is more than 6500, I can't see how this should be all.

My plan:

Win32::GUI v1.04 will issue the following warning for 'use Win32::GUI;', 
whilst still exporting the same 300+ constants:
"'use Win32::GUI;' is currently exporting constants into the callers 
scope. This functionality is deprecated. Use 'use Win32::GUI();' or list 
your required exports explicitly instead. Used at FILENAME line LINENUMBER."

Win32::GUI v1.05 will stop exporting the 300+ constants, and will warn 
that that is what it has done.  Something like:
"'use Win32::GUI;' behaviour has changed since v1.04: better written as 
'use Win32::GUI();'.  Used at FILENAME line LINENUMBER."

Win32::GUI v1.06 will stop issuing the warning, whilst maintaining the 
v1.05 behaviour.


Compare this with use of Win32::GUI::constant("ES_WANTRETURN");

In 1.04, a warning issued, but old functionality remains:
"Use of Win32::GUI::constant() is deprecated. Use 
Win32::GUI::Constants::constant() instead.  Used at FILENAME line 
LINENUMBER."

In 1.05, it will die with a message:
"Use of Win32::GUI::constant() has been removed. Use 
Win32::GUI::Constants::constant() instead.  Used at FILENAME line 
LINENUMBER."

In 1.06 the function will not exist.


And finally with the if($a = Win32::GUI::ESWANTRETURN) usage:

In 1.04, a warning:
Use of 'Win32::GUI::ES_WANTRETURN' is deprecated. Use 
'Win32::GUI::Constants::ES_WANTRETURN' instead.  Used at FILENMAE line 
LINENUMBER."

In 1.05, death:
Use of 'Win32::GUI::ES_WANTRETURN' has been removed. Use 
'Win32::GUI::Constants::ES_WANTRETURN' instead.  Used at FILENMAE line 
LINENUMBER."

In 1.06 you'll probably get a warning from perl about an undefined 
subroutine.


Of course, spotting any of this in the 1.04 release depends on the use 
script running with warnings on - without that the first thing you'll 
notice is your script failing/dying under 1.05 ....

Does this work?

Rob.