Where Find Notice of API Changes

I just noticed that in Access.pm:

sub checkAccessPermission {
    my( $this, $mode, $user, $text, $topic, $web ) = @_;

sub checkAccessPermission {
    my( $this, $mode, $user, $text, $meta, $topic, $web ) = @_;

To access the functionality, I do:

$session->{security}->checkAccessPermission(

Which I thought was the right way to access it.

-- Contributors: EricHanson - 18 May 2007

Discussion

The first thing to note, is that if its not in TWiki::Func, its not in the API. After that rather un-helpful statement, I am sorry to have to follow up that I don't know where the changes to TWiki::Func API are documented. Though I presume the distributed documentation found in TWikiFuncDotPm would have some relevance.

-- SvenDowideit - 18 May 2007

There are a couple of answers

• Changed are documented in the release note. In this case it was there but maybe not very visible. It is one of the bug fixes in 4.1.2 and it is in the table. I think in future changes to the official API should be in important changes.
• If you look at the TWikiFuncDotPm in your own 4.1.2 and you look at the rdiff you see what changed since last release.
• As Sven points out functions in Access.pm are not API. You should use the equivalent TWiki::Func::checkAccessPermission.
• The change made was discussed in detail to ensure that the change was backwards compatible (assuming using the official API)

-- KennethLavrsen - 19 May 2007

All changes to the TWiki::Func API should be documented in the headers to the functions. Where a function has been added, it is marked as "Since" a specific rev. Where an additional parameter has been added, this is also marked. Where a function has been deprecated (discouraged) it is marked as "DEPRECATED", though all deprecated functions should still work as documented. Note that no function has been removed from TWiki::Func, since rev 1.000, and all new parameters on existing functions are optional.

Having said all that, if you are writing core code, then sorry, the internal interfaces will change, frequently and often extensively. If you are writing a Contrib, then call TWiki::Func as your first choice or, if the function you require is not avaiable through Func, then heavily document that fact, raise a RFC to get the function accessible through Func, scream, weep and moan, and only then should you reluctantly call the core function, recognising that the function interface may change without warning under your feet.

-- CrawfordCurrie - 19 May 2007

DontShipDotPmTopics is a proposal to reduce the chance of using unofficial functions.

-- PeterThoeny - 20 May 2007

Peter: I didn't find out about it through the topics, but rather by looking at the source code, and seeing what other stuff did for the effect I wanted.

Rather than not shipping some topics, more clear redirection to Func would probably help. I couldn't find anything in Store.pm or Access.pm that told me I shouldn't be using those files, but instead use Func. Seems like the most eyes will be on the source code...

-- EricHanson - 08 Jun 2007