This topic is not quite right for 4.2 and beyond, we are in the process of updating it.

This manual process is being replaced by the buildTWikiRelease.pl script

Reminder to Kenneth and Sven: Need to change the sequence below so that the Patch branch is made at feature freeze and releases always created from the Patch branch. See PatchReleaseMaintenanceSVN. (Sven will modify the script as we nail down the details of the process to be able to release from the appropriate places.)

How to Build a Release

It is an important principle of TWiki Release 4 and beyond that anyone can build a release of TWiki using the automatic tools, given nothing more than some standard F/OSS tools and an SVN checkout area. The following sections describe the stages that need to be gone through to correctly build a Beta or Final release.

The contents of a TWiki release are specified by the contents of the tools/MANIFEST file. Optional modules, such as plugins, are generally listed at the end using !include statements.

The instructions relate to building the TWikiForGeneralRelease using the the tools/build.pl build script.

Releases are built on Linux platforms, so the instructions are for Linux. It should be possible to generate a release on Windows, but it's untested.

Current nightly build process (using TWikiRelease04x02) - Runs nightly at 4am Sydney time. (GMT+10)

Note: when there is an official beta release, it will be uploaded to TWiki.org

curl http://svn.twiki.org/svn/twiki/branches/TWikiRelease04x02/tools/buildTWikiRelease.pl > buildTWikiRelease.pl
perl buildTWikiRelease.pl

This will create tgz and zip files named using the verion number in TWiki.pm, and appending the svn repository number to get files named like TWiki-4.2.0-beta1-auto14551.zip.

Note: The script will abort if there are unit test failures. (sending an email to the TWikiDevMailingList)

The builds will be uploaded to TWikiRelease04x02 Nightly build area

Current nightly build process (from trunk) - Runs nightly at 4am Sydney time. (GMT+10)

curl http://svn.twiki.org/svn/twiki/trunk/core/tools/buildTWikiRelease.pl > buildTWikiRelease.pl
perl buildTWikiRelease.pl

This will create tgz and zip files named using the verion number in TWiki.pm, and appending the svn repository number to get files named like TWiki-4.2.0-auto14551.zip.

Note: The script will abort if there are unit test failures. (sending an email to the TWikiDevMailingList)

The builds will be uploaded to MAIN Nightly build area

---

Build procedure for 4.1.X and 4.2.X (manually)

Note: at this time, this document and the build script is heavily biased towards creating official TWiki.org releases

Before generating a release package:

1. need a SVN checkout (see SubversionReadme)
   • Checkout core to a clean build area
     • svn co http://svn.twiki.org/svn/twiki/branches/TWikiRelease04x02/core
     • Checkout default plugins:
       • svn co http://svn.twiki.org/svn/twiki/branches/TWikiRelease04x02/CommentPlugin
       • ...etc
   • once you have a clean checkout area you can re-use it for subsequent builds. just
     • svn up
     • svn diff should show no results
     • svn status | grep '?' | sed 's/?/rm/' | sh
     • # or similar, gets rid of local files
2. Install default plugins (symbolic-link)
   • perl pseudo-install.pl -link default to install the plugins specified in MANIFEST
3. use the configure script to make your system basically functional
   • CPAN prerequisites: CPAN:CGI::Session
   • ensure that your apache has sufficient file and directory permissions for data and pub
4. Run the unit tests
   • cd test/unit
   • export TWIKI_LIBS=
   • export TWIKI_HOME=
   • perl ../bin/TestRunner.pl TWikiSuite.pm
5. Run the TestCaseAmISane sanity check manual testcase
6. Install the TestFixturePlugin perl pseudo-install.pl -link TestFixturePlugin
   • Do not enable TestFixturePlugin in configure
   • CPAN prerequisites: CPAN:HTML::Tagset CPAN:HTML::Parser
7. Run all the automatic testcases in the TestCases web (use firefox, and open each 'run' link in a new tab)
   • Enable $TWiki::cfg{INCLUDE}{AllowURLs}  = "enabled"; in the Security settings | Miscellaneouss area of configure in order to run Develop:TestCases.TestCaseAutoIncludeAttachment
   • You should see ALL TESTS PASSED on all test pages. If you see the test itself, something is not configured correctly (check CPAN dependencies).
8. check for memory leaks by running tools/MemoryCycleTests.pl
   • CPAN prerequisites: Devel::Monitor
9. Check the manifest cd tools; perl check_manifest.pl
   • Some files (top level .html, *DotPm.txt in TWiki web, and AUTHORS attachments to TWikiContributor topic in Main and TWiki webs are generated by the build process in the staging area, and do not appear in the MANIFEST.
   • Expect to see the following warnings; they are OK:
     The following files were found in subversion, but are not in MANIFEST
bin/update-develop-links
lib/TWiki/Store/Subversive.pm
10. Check that all doc topic have correct TOPICINFOs
    • cd data; grep '%META:TOPICINFO{' */*.txt | grep -v TestCases | grep -v 'author="TWikiContributor".*version="\$Rev'
11. fix up release notes with new changelogs - see
    • http://develop.twiki.org/~twiki4/cgi-bin/view/Bugs/ReleaseNotesTml?type=patch
    • Note that the release note is edited by editing the topic data/TWiki/TWikiReleaseNotes04x00. The build script creates a file in the root of the zip called TWikiReleaseNotes04x00? .html, and the build script needs your Twiki to be running to look up the release note topic and show it with the simple text skin.
    • Note - from 4.1 we need to call this data/TWiki/TWikiReleaseNotes04x01

Build a test release package

• do this from a freshly cleaned checkout - see step one above

1. Install default plugins (hard copy)
   • perl pseudo-install.pl default to install the plugins specified in MANIFEST
2. use the configure script to make your system basically functional
   • ensure that your apache has sufficient file and directory permissions for data and pub
3. cd lib
4. perl ../tools/build.pl release
   • Note: if you specify a release name the script will attempt to commit to svn

After the package is built, but before it is uploaded

1. unarchive the .tgz in a clean area
2. make sure that the generated files are all correct
3. configure apache and run configure, make sure it works
   • you may have to change the permissions or ownerships of the files to match your apache setup (chown -R www-data.www-data * works on my debian system)
4. Verify that all expected plugins are installed and functioning

Build a final release package and upload to Codev web

1. Clean the build area again (see above)
2. Install default plugins
   • perl pseudo-install.pl -link default to install the plugins specified in MANIFEST
3. use the configure script to make your system basically functional
4. cd tools
5. perl build.pl upload
   • please specify a release name (eg. 4.0.0-rc1, 4.0.3), and commit to svn
   • This will build and upload the release package to TWiki:Codev.TWikiRelease??x??x??
   • CPAN prerequisites: CPAN:LWP
6. follow ProductionReleaseChecklist
7. For patch releases:
   • Create patch log - http://develop.twiki.org/~develop/cgi-bin/view/Bugs/ReleaseNotes?type=patch
   • Create changed files zip file, possibly also patch file
   • diff --ignore-all-space --ignore-blank-lines --unified --recursive --new-file twiki402/ zip/ > TWiki-4.0.3-patch.diff
   • grep "+++ twiki403" TWiki-4.0.3-patch.diff > TWiki-4.0.3-filelist-changed.txt

create a release tag, and if its a new major release, a release branch

1. create an svn tag from the released version (you NEED to know the revision number that was commited when creating the final release package)
   svn copy -r *REV* http://svn.twiki.org/svn/twiki/branches/TWikiRelease04x02/ http://svn.twiki.org/svn/twiki/tags/TWikiRelease*RELEASENAME*
2. checkout that new tag
3. unzip the previously created package into the checkout, do an svn add and and svn commit
   • the ,v files are later used by the next release build. (and to track actually released files)
4. Note that from 4.1 the build script automatically search the tags and create ,v files based on the latest release. So no hacking of the tools/build.pl is needed anymore.

new release maintenance branch

1. create an svn branch from the released version (you NEED to know the revision number that was commited when creating the final release package)
   svn copy -r *REV* http://svn.twiki.org/svn/twiki/branches/TWikiRelease04x02/ http://svn.twiki.org/svn/twiki/branches/Patch*RELEASENAME_WITHOUTPATCHNUMBER*

After the package has been uploaded

1. Install the BuildContrib perl pseudo-install.pl -link BuildContrib
2. Use tools/build_all_extensions.pl upload to build and upload all the extensions packages
   • This will build and upload the release package to TWiki:Plugins.TWiki

Notes:

1. Any individual plugin can be "released" by building the module in the build area ( export TWIKI_LIBS=/path/to/twiki/lib; cd twikiplugins/Module/lib/TWiki/Plugins/Module; perl build.pl release ) and manually uploading the updated zip to TWiki:Plugins.

-- Contributors: CrawfordCurrie, WillNorris, PeterThoeny, SvenDowideit, KennethLavrsen

Discussions

Some minor corrections above.

-- RichardDonkin - 28 Aug 2007

start to convert to new post Freetown release svn/twiki/trunk