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.
