Using Subversion to track the latest TWiki developments

If you wish to use the latest development versions of TWiki, you can use Subversion to keep up to date.

What is Subversion?

Subversion is a revision control system. It records all the source code, and tracks changes to that source code.

It can be downloaded from http://subversion.tigris.org/. A Windows shell extension client is available at http://tortoisesvn.tigris.org/, and a cross-platform GUI at http://rapidsvn.tigris.org/. There is also a book about Subversion usage online at http://svnbook.red-bean.com/

See Installing Subversion Client

How does TWiki use Subversion?

The TWiki project has a subversion server at http://svn.twiki.org/svn/ that we use to store and track changes to the TWiki source code, and the source code of many extensions. You don't have to use subversion to contribute to TWiki, but you'd have to have a pretty strong reason not to.

The trunk is used to check in all bug fixes and new code targeted at the next release. It is a requirement that the code on the trunk always works, as we use it to run the bugs server at http://develop.twiki.org/~twiki4/cgi-bin/view, and most developers rely on it always working for their development environments. So you have to take great care checking code into the trunk.

Due to the nature of development code, major bugs or issues will occasionally be encountered in this code.

When a TWiki release is made, then release branches are created to track minor fixes and security fixes to that code, so that the trunk can move ahead without getting dragged down by old releases. Developers can also create other branches in the twiki/scratch area if they want to try out new ideas.

The code checked into the trunk is used to drive a TWiki at http://develop.twiki.org/~twiki4/cgi-bin/view, which is used to serve the bugs database. This checkout area is kept up to date by cron job that runs every 10 minutes. In the best case, the person doing the checkin will be able to almost immediately check the correct functioning of their checkin.

The trunk is also used for TWiki extensions, which sometimes follow the same release cycle as the core code, but often don't. Extension developers can use the trunk without fear of breaking the bugs database, as long as they:

1. Don't check into any of the 'standard' plugins that are installed by default with a TWiki release (see core/lib/MANIFEST).
2. Check only into Extension named subdirectories (e.g. MyNewPlugin)

How to check out the trunk

To check out the trunk including the core and all =extensions=

mkdir twiki
cd twiki
svn co http://svn.twiki.org/svn/twiki/trunk .

A AccessStatsPlugin/
A ActionTrackerPlugin/
A AddDBMGroupPlugin/
......
A core

...

If you leave out the "." at the end of the svn co command, it will create a directory named trunk for you.

This will check out everything on the trunk - including every extension that has ever been checked in. if you don't want this, and only want to check out a subset of the bits you need, see Checking Out a Subset

See SubversionBasedTWikiInstall for practical advice on using a SVN checkout as a live install.

See HowToStartExtensionDevelopmentInSubversion if you work on extensions.

How to check out a release branch

There is a branch for each release. There may be other developer branches as well, depending on what is going on.

See http://svn.twiki.org/svn/twiki/branches/ for the branches. Shipping releases are currently in branches labelled TWikiReleaseNNxNN, i.e., the shipping code for release 4.1.x is in branch TWikiRelease04x01. Note that pre-4.2.0, the branch tags were changed to PatchNNxNN.

The list of tags can be found at http://svn.twiki.org/svn/twiki/tags/.

How to check in

The trunk has "trigger scripts" on it that enforce the following rules:

1. All checkins must have a comment
2. Checkin comments must list all the Item numbers in Bugs web that document the reason for the change
3. Items must be open at the time of checkin (be in Open, Actioning or Waiting for Feedback states)

svn commit -m "Item4815: Corrected inability to open hatch Item4900: Closed hatch to shut out freezing water"

This is to make sure that we have traceability of all changes. These comments are used to update the linkage between items in the Bugs web and checkins in Subversion, so you should try hard to make sure they are accurate and complete.

Branches don't have trigger scripts, so there is no constraint on what message you use when you check in.

If you have been given write access to the repository, you should use the same login and password as your twiki.org WikiName.

Generating Patches

Even if you can't check in, you can still contribute. Make your changes in your checkout area, and then cd to the root directory of the checkout area and:

svn update
svn diff > mypatch.diff

Attach the file mypatch.diff to the relevant topic in Bugs web (there should be one topic for each change) and ask someone with checkin rights to merge it.

Please ensure the TWikiUnitTests are run if possible, and always run through the tests in the TestCases web in your checkout area.

Watching

Check-ins are automatically mailed to the twiki-dev mailing list. See twiki-dev@listsPLEASENOSPAM.sourceforge.net.

An RSS feed at http://develop.twiki.org/~twiki4/pub/svn2rss.xml is also generated on SVN commits.

Scratch area in SVN

http://svn.twiki.org/svn/twiki/scratch is an area for Developers to try out ideas, either a temporary branch, or new twiki related ideas. Anyone with checkin access can create new branches.

To create a new branch of the core code (derived from the trunk) under scratch,

svn copy http://svn.twiki.org/svn/twiki/trunk/core http://svn.twiki.org/svn/twiki/scratch/NewBranchName

For doing the copy, you will be asked for a commit message. You should include an Item number from the Bugs web e.g.

Item90210: Branch for doing performance experiments.

Then go back to checking out a branch, substituting the URL of the new branch.

Checking Out a Subset

The trunk checkout instructions above will check out the TWiki core and every extension. Often you will want to check out just a subset of the code specific to what you are working on or testing. This can save an awful lot of disc space, as well as making subversion commands much faster and more manageable.

The best way to do this is to create a root directory for all your TWiki work. For example, "~/httpdocs/twiki". Then check out the core from the trunk (or whatever release banch you are working on):

cd ~/httpdocs/twiki
svn co http://svn.twiki.org/svn/twiki/trunk/core core

This will checkout the core to the core subdirectory. Now you can checkout the subset of extensions you want to have available:

svn co http://svn.twiki.org/svn/twiki/trunk/TWikiUserMappingContrib TWikiUserMappingContrib
svn co http://svn.twiki.org/svn/twiki/trunk/CommentPlugin CommentPlugin
svn co http://svn.twiki.org/svn/twiki/trunk/EditRowPlugin EditRowPlugin

(note: if you intend to build a TWiki release, you will need to checkout all the extensions listed in core/lib/MANIFEST)

Now you can use core/pseudo-install.pl to soft-link (Linux/BSD etc) or copy (Windows) the extensions into the core. For example:

cd ~/httpdocs/twiki/core
perl pseudo-install.pl default

(some day someone will write a script to do all this in one step. Some day....)

See Also

See also MergingInSubversion, DeveloperResponsibilities, BuildingARelease

FAQ

Subversion already has rich FAQs, and Google is your friend, so this FAQ is restricted to questions that relate to the TWiki project's specific use of subversion.

• Do we have something like ViewCVS or even better a SvnPlugin to access the SVN repository? -- StephaneLenclud - 17 Sep 2006
  • No - the svn.twiki.org server is running a rather 'secure' version of CentOS, and all the existing svn repository browsers require alot of configuration and mangement. Ideally, we could do with a set of TWiki based tools that give that sort of version browsing on anything in a supported TWikiStore (and then the SubversionStore needs completing)
• How do I change my local SVN installation to point to the new MAIN branch? Use this command:

svn diff > ../BackupChanges.diff
svn switch http://svn.twiki.org/svn/twiki/trunk .

NOTE the little dot at the end. For more details check the SVN online manual: http://svnbook.red-bean.com/en/1.2/svn-book.html#svn.ref.svn.c.switch

Contributors: WalterMundt, SvenDowideit, MartinCleaver, WillNorris, MattWilkie, CrawfordCurrie, LynnwoodBrown, MichaelRubin

Discussion

I have a subversion based install running the main branch. If I was to commit a new plugin, where would I run svn commit from? The twiki root, or from /twikiplugins, or even /twikiplugins/NewPlugin?

Just want to check as I have made changes to TWikiUsers and TWikiPreferences, and obviously they shouldn't be committed.

-- AndrewRJones - 04 May 2007

You can do both: either cd to the directory where your changes are located, or from the TWiki root, if you give the path what should be committed. So, the following example works:

$ cd twikiplugins/NewPlugin
$ svn commit -m 'Item007: Track down Blofeld'

...as does the following (from TWiki root):

$ svn commit -m 'Item007: Track down Blofeld' twikiplugins/NewPlugin

Neither will commit anything outside of twikiplugins/NewPlugin. By the way: I think that every TWiki developer has committed "too much" at least once in his career. As an additional safeguard I usually run svn diff with the same path parameter before svn commit to check what will be transferred.

-- HaraldJoerg - 04 May 2007

ALWAYS do an svn diff before checking in.

-- WillNorris - 04 May 2007

Thanks for you help. For a new plugin, I found svn status to be better, as it only lists the modified files, not each added line.

-- AndrewRJones - 08 May 2007

Hm... it seems that the RSS feed is broken again (last listed revision is #14059 from 2007-06-08, and the body of all entries contain a link to the root twiki/ directory of current revision #16305 as of this writing)

-- MarkusUeberall - 28 Jan 2008

How can I checkout the core from a tag or branch? I can't find the /core directory as in trunk, but still all plugins and extensions are in the directory. Seems this is not up to date: "_Then check out the core from the trunk (or whatever release branch you are working on)_"

I would like to checkout TWiki v4.2 from svn and have the possibility to make a svn switch to the following versions.

-- CedricWeber - 25 Apr 2008