Tags:
create new tag
, view all tags
TWiki::Func::getOopsUrl has problems (Bugs:Item3772). It's also a restricted subset of getScriptUrl.

It's pointless, and needs to be deprecated.

=pod

getOopsUrl( $web, $topic, $template, $param1, $param2, $param3, $param4 ) -> $url

Compose fully qualified 'oops' dialog URL

  • $web - Web name, e.g. 'Main'. The current web is taken if empty
  • $topic - Topic name, e.g. 'WebNotify'
  • $template - Oops template name, e.g. 'oopsmistake'. The 'oops' is optional; 'mistake' will translate to 'oopsmistake'.
  • $param1 ... $param4 - Parameter values for %PARAM1% ... %PARAMn% variables in template, optional
Return: $url URL, e.g. "http://example.com:80/cgi-bin/oops.pl/ Main/WebNotify?template=oopslocked&param1=joe"

DEPRECATED since 1.1, the recommended approach is to throw an oops exception.

   use Error qw( :try );

   throw TWiki::OopsException($web, $topic, undef, 0, [ 'I made a boo-boo' ]);
If this is not possible (e.g. in a REST handler that does not trap the exception) then you can use getScriptUrl instead:
   my $url = TWiki::Func::getScriptUrl($web, $topic, 'oops',
            template => 'oopsmistake',
            param1 => 'I made a boo-boo');
   TWiki::Func::redirectCgiQuery( undef, $url );
   return 0;

Since: TWiki::Plugins::VERSION 1.000 (7 Dec 2002)

=cut

Tracked in Bugs:Item3772

-- Contributors: CrawfordCurrie - 06 Apr 2007

Discussion

This proposal has not been through the proper release procedure.

Deprecating API needs to be decided at release meetings. This has been pointed out over and over again.

To make a qualified decision if the function is to be deprecated I would like to know which plugins (of those checked into the TWiki Subversion) uses the old function and if the proposed change above will work for the plugin.

A quick search shows

That is a good long list of many fine plugins. Most are plugins that are still working fine. I personally use many of them.

So if we decide to deprecate the getOopsUrl what is then the plan for all these plugins?

Are we again telling all the plugin authors to rewrite their code to ensure the plugin also works a year from now?

Or is the proposer going to rewrite them all?

-- KennethLavrsen - 07 Apr 2007

As pointed out many times, deprecation is not removal. We have - to the best of my knowledge - never removed a deprecated function from the interface, and I don't see us starting here. We'll keep the function as long as any working plugin is using it, without the need for anyone to go in and forcibly rewrite.

The proposed change works for all uses of getOopsUrl. Code targeted at old TWiki releases needs to continue to use the old API.

If the next release meeting feels that this deprecation is inappropriate, I will of course revert the change - it's only one word in the documentation, after all. But this one is a no-brainer.

  • SVN r13287 has extensive changes. getOopsUrl is removed from TWiki.pm, and Func's getOopsUrl calls getScriptUrl. Is this a compatible change, e.g. works properly with absolute vs relative URL, parameter list, URL encoding, using default web/topic if empty, aware of 'keep' parameter, etc? -- PeterThoeny - 08 Apr 2007

-- CrawfordCurrie - 07 Apr 2007

I have always understood that Deprecation is the signal that the function will be later be removed.

So I just looked up the word in Wikipedia http://en.wikipedia.org/wiki/Deprecation

and I see that the word actually means something differently than what I got out of seeing the translation in my Gyldendals English-Danish dictionary which has a non-computer-world translation.

I guess the reason I (and others) always received the word deprecation as intension to remove is the deprecation of plugin handlers. If we do not intend to ever remove those handlers why on earth do the users still have to read a silly warning about the use of deprecated handler in the %FAILEDPLUGINS% table? We had large discussions in the community about deprecation of plugin handlers where it was clear that the intension was to remove them. It was discussed that plugin authors should have minimum 1 year before the handlers were removed. This year has passed and the handlers are still there.

So maybe we need two different warnings. A warning that a feature is obsolete (will be removed) and a warning that a feature is deprecated (will stay - but better alternative is recommended for various reasons).

So the signal you want to send for getOopsUrl is - not recommended?

You do not intend to ever remove the function getOopsUrl from the API or make changes in the code so it stops working?

Then I have no problem with it. But please - deprecation is still a release meeting subject in my view. I do not mind that no-brainers are implemented without waiting for decision when reverting is easy like in this case. But please do not mark it as done in TWikiFeature04x02 because then it gets off the radar and not brought up at next release meeting and the customer advocate role becomes impossible.

-- KennethLavrsen - 07 Apr 2007

Standard practice is to deprecate a function until you are pretty much certain that no-one is using it, before you ever consider removing it. The warnings are there specifically to deprecate the handlers i.e. to try and stop anyone from using them, so we can remove them. As long as the warnings are still seen for some plugins, then we can't obsolete them. But the ultimate end goal of deprecation is always removal, it just may take a long time.

-- CrawfordCurrie - 07 Apr 2007

Like Kenneth pointed out, we should try hard to follow the process we all agreed on. This is the only acceptable way to make decisions on controversial issues we have within the community.

Here is my personal take: We cannot deprecate a popular TWiki API function just because it is not sufficient for one new case (error reporting in a REST app, as reported in Bugs:Item3772). We had enough problems with the API in TWiki 4 that resulted in many plugins still not updated to TWiki 4, and a partially successful call to HandlingCairoDakarPluginDifferences in a compatible way (with is possible only with some extra effort). The proper solution is to add a new function that fulfills the needs of REST programming, or to enhance getOopsUrl in a compatible way. As for the plugins I maintain, I would rather spend my time in enhancements than in adding yet more conditional code to keep my plugins compatible with several TWiki versions. The Func API is a promise to plugin coders that they can rely a stable set of function calls.

So, lets revert the deprecation of this popular API call, and bring this suggestion to a release meeting where we can make an informed decision.

-- PeterThoeny - 08 Apr 2007

I think we can vote for this one at the 09 Apr release meeting.

If someone wants to vote but cannot make the meeting, please cast your vote below.

Who Vote
   

-- KennethLavrsen - 08 Apr 2007

Once again (patiently) deprecation does not mean removal. It means the function is marked in such a way as to discourage it's use. See Wikipedia:deprecation. Note that in all cases I am aware of, conditional code is only needed where plugin authors have bypassed the plugins API, or have chosen to write code to support newer APIs even though the old APIs are still maintained.

Note that there is no need for a new function. getScriptUrl is already a superset of the functionality offered by getOopsUrl.

-- CrawfordCurrie - 09 Apr 2007

At the FreetownReleaseMeeting2007x04x09 it was decided to deprecate this function.

-- PeterThoeny - 10 Apr 2007

Done.

CC

Edit | Attach | Watch | Print version | History: r13 < r12 < r11 < r10 < r9 | Backlinks | Raw View | Raw edit | More topic actions
Topic revision: r13 - 2007-04-25 - KennethLavrsen
 
  • Learn about TWiki  
  • Download TWiki
This site is powered by the TWiki collaboration platform Powered by Perl Hosted by OICcam.com Ideas, requests, problems regarding TWiki? Send feedback. Ask community in the support forum.
Copyright © 1999-2017 by the contributing authors. All material on this collaboration platform is the property of the contributing authors.