• Do not register here on develop.twiki.org, login with your twiki.org account.
• Use View topic Item7848 for generic doc work for TWiki-6.1.1. Use View topic Item7851 for doc work on extensions that are not part of a release. More... Close
• Anything you create or change in standard webs (Main, TWiki, Sandbox etc) will be automatically reverted on every SVN update.
Does this site look broken?. Use the LitterTray web for test cases.

Item3895: Structure the TWiki version number to make accessible from plugins (code included)

Item Form Data

AppliesTo: Component: Priority: CurrentState: WaitingFor: TargetRelease ReleasedIn
Engine Documentation Normal Closed   minor 4.2.0

Edit Form Data

Summary:
Reported By:
Codebase:
Applies To:
Component:
Priority:
Current State:
Waiting For:
Target Release:
Released In:
 

Detail

To deal with recent enhancements plugin authors need to check the TWiki version number, in a structured manner.

Proposed code (works):

=pod

---+++ getTWikiVersion( ) -> %version

Get major, minor, patch version numbers from the TWiki version.

Return: =%version=  Hash containing the parameters "major", "minor", "patch"

*Since:* TWiki::VERSION 4.1.3

Example:

my %version = TWiki::Func::getTWikiVersion();
my $majorVersion = $version{"major"};
my $minorVersion = $version{"minor"};
my $patchVersion = $version{"patch"};

=cut

sub getTWikiVersion() {
    my $release = $TWiki::RELEASE;
    $release =~ /[A-Za-z\-]*([0-9]).([0-9]).([0-9])/;
    my ( $major, $minor, $patch ) = ( $1, $2, $3 );
   my %version = ( major => $major,
                   minor => $minor,
                   patch => $patch );
   return %version;
}

Of course we must agree that VERSION always ends with the major.minor.patch numbers.

I can imagine the main code is in TWiki.pm and Func.pm just calls the function.

-- TWiki:Main/ArthurClemens - 14 Apr 2007

In the past plugins have only depended on the API version - $TWiki::Plugins::VERSION - which is incremented in a controlled manner, such that it identifies each functionality increment a plugin author needs to know about.

I would not like to see a new versioning numbering mechanism, especially not since we had such fun discussing this topic before.

What "recent enhancements" do you mean, and why isn't incrementing $TWiki::Plugins::VERSION sufficient?

CC

I was motivated because I wanted to use sanitizeAttachmentName for AttachContentPlugin and BatchUploadPlugin. These plugins currently have their own sanitizing code. But sanitizeAttachmentName is not yet released. So unless the plugin version is bumped with each TWiki (patch) release, there is no way to tell when a plugin can use this code.

-- TWiki:Main.ArthurClemens - 14 Apr 2007

I also think that we should stick to the current $TWiki::Plugins::VERSION number, it is sequential and simple.

What is missing though is a prominent place to look up the version info per release. The plugins version number is currently not documented; the SVN version number is scattered in TWiki:Codev/TWikiBetaRelease, TWiki:Codev/TWikiRelease04x00, TWiki:Codev/TWikiRelease04x01 and a few other topics.

-- TWiki:Main.PeterThoeny - 14 Apr 2007

  • Is a list of changed functionalities published alongside TWikiHistory?
  • When does the number get updated? At each minor TWiki release?

-- TWiki:Main.ArthurClemens - 14 Apr 2007

The number gets bumped up with each minor TWiki release if the plugin api is enhanced.

I do not think TWikiHistory is the right place. Possibly a new TWiki.TWikiReleases topic that lists all version info of all previous releases. Not sure if this should be a distribution document or a supplemental document.

-- TWiki:Main.PeterThoeny - 14 Apr 2007

I agree that doc is the right approach.

I think that an API history summary should be maintained at the top of the TWiki::Func module - after all, that's where it matters.

Changing to doc.

CC

added API summary to lib/TWiki/Func.pm :

Version 1.000:
        checkAccessPermission( $type, $wikiName, $text, $topic, $web, $meta ) -> $boolean
        expandCommonVariables( $text, $topic, $web, $meta ) -> $text
        extractNameValuePair( $attr, $name ) -> $value
        (deprecated) formatGmTime( $time, $format ) -> $text
        getCgiQuery( ) -> $query
        (deprecated) getDataDir( ) -> $dir
        getDefaultUserName( ) -> $loginName
        getMainWebname( ) -> $name
        (deprecated) getOopsUrl( $web, $topic, $template, $param1, $param2, $param3, $param4 ) -> $url
        getPreferencesFlag( $key, $web ) -> $value
        getPreferencesValue( $key, $web ) -> $value
        (deprecated) getPubDir( ) -> $dir
        (deprecated) getPublicWebList( ) -> @webs
        getPubUrlPath( ) -> $path
        getRevisionInfo($web, $topic, $rev, $attachment ) -> ( $date, $user, $rev, $comment )
        getScriptUrl( $web, $topic, $script, ... ) -> $url
        (deprecated) getScriptUrlPath( ) -> $path
        getSessionValue( $key ) -> $value
        getSkin( ) -> $skin
        getTopicList( $web ) -> @topics
        getTwikiWebname( ) -> $name
        getUrlHost( ) -> $host
        getViewUrl( $web, $topic ) -> $url
        getWikiName( ) -> $wikiName
        getWikiToolName( ) -> $name
        getWikiUserName( ) -> $wikiName
        internalLink( $pre, $web, $topic, $label, $anchor, $createLink ) -> $text
        isGuest( ) -> $boolean
        (deprecated) permissionsSet( $web ) -> $boolean
        readFile( $filename ) -> $text
        readTemplate( $name, $skin ) -> $text
        readTopic( $web, $topic, $rev ) -> ( $meta, $text )
        redirectCgiQuery( $query, $url, $passthru )
        renderText( $text, $web ) -> $text
        saveFile( $filename, $text )
        saveTopic( $web, $topic, $meta, $text, $options ) -> $error
        setSessionValue( $key, $value ) -> $boolean
        topicExists( $web, $topic ) -> $boolean
        userToWikiName( $loginName, $dontAddWeb ) -> $wikiName
        webExists( $web ) -> $boolean
        wikiToUserName( $wikiName ) -> $loginName
        writeHeader( $query, $contentLength )
Version 1.010:
        checkTopicEditLock( $web, $topic, $script ) -> ( $oopsUrl, $loginName, $unlockTime )
        readTopicText( $web, $topic, $rev, $ignorePermissions ) -> $text
        saveTopicText( $web, $topic, $text, $ignorePermissions, $dontNotify ) -> $oopsUrl
        setTopicEditLock( $web, $topic, $lock )
Version 1.020:
        formatTime( $time, $format, $timezone ) -> $text
        getRegularExpression( $name ) -> $expr
        writeDebug( $text )
        writeWarning( $text )
Version 1.021:
        getPluginPreferencesFlag( $key ) -> $boolean
        getPluginPreferencesValue( $key ) -> $value
Version 1.025:
        (deprecated) checkDependencies( $moduleName, $dependenciesRef ) -> $error
        extractParameters($attr ) -> %params
Version 1.1:
        addToHEAD( $id, $header )
        attachmentExists( $web, $topic, $attachment ) -> $boolean
        clearSessionValue( $key ) -> $boolean
        createWeb( $newWeb, $baseWeb, $opts )
        expandTemplate( $def  ) -> $string
        expandVariablesOnTopicCreation ( $text ) -> $text
        getContext() -> \%hash
        getListOfWebs( $filter ) -> @webs
        getRevisionAtTime( $web, $topic, $time ) -> $rev
        getWorkArea( $pluginName ) -> $directorypath
        isValidWikiWord ( $text ) -> $boolean
        loadTemplate ( $name, $skin, $web ) -> $text
        moveAttachment( $web, $topic, $attachment, $newWeb, $newTopic, $newAttachment )
        moveTopic( $web, $topic, $newWeb, $newTopic )
        moveWeb( $oldName, $newName )
        normalizeWebTopicName($web, $topic) -> ($web, $topic)
        readAttachment( $web, $topic, $name, $rev ) -> $data
        registerRESTHandler( $alias, \&fn, )
        registerTagHandler( $var, \&fn, $syntax )
        saveAttachment( $web, $topic, $attachment, $opts )
        searchInWebContent($searchString, $web, \@topics, \%options ) -> \%map
        sendEmail ( $text, $retries ) -> $error
        wikiToEmail( $wikiName ) -> $email
Version 1.12:
        emailToWikiNames( $email, $dontAddWeb ) -> @wikiNames
        getExternalResource( $url ) -> $response
        wikiNameToEmails( $wikiname ) -> @emails
Version 1.13:
        isTrue( $value, $default ) -> $boolean
        popTopicContext()
        pushTopicContext($web, $topic)
        spaceOutWikiWord( $word, $sep ) -> $text

WN

Cleaned "WaitingFor" field.

-- TWiki:Main.GilmarSantosJr - 10 Aug 2008

ItemTemplate
Summary Structure the TWiki version number to make accessible from plugins (code included)
ReportedBy TWiki:Main.ArthurClemens
Codebase

SVN Range TWiki-4.1.2, Fri, 13 Apr 2007, build 13369
AppliesTo Engine
Component Documentation
Priority Normal
CurrentState Closed
WaitingFor

Checkins TWikirev:13814 TWikirev:13815 TWikirev:13931 TWikirev:13955
TargetRelease minor
ReleasedIn 4.2.0
Edit | Attach | Watch | Print version | History: r17 < r16 < r15 < r14 < r13 | Backlinks | Raw View | Raw edit | More topic actions
Topic revision: r17 - 2008-08-10 - GilmarSantosJr
 
This site is powered by the TWiki collaboration platform Powered by PerlCopyright © 2008-2019 by the contributing authors. All material on this collaboration platform is the property of the contributing authors.
Ideas, requests, problems regarding TWiki? Send feedback