How to Build a Release

Introduction

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.

NOTES:

• This manual process is being replaced by the buildTWikiRelease.pl script
• 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. (We will modify the script as we nail down the details of the process to be able to release from the appropriate places.)

Build procedure for TWiki-5.1.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/TWikiRelease05x01
   • 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)
   • cd core
   • perl pseudo-install.pl default to install the plugins specified in MANIFEST
   • perl pseudo-install.pl UnitTestContrib
   • perl pseudo-install.pl TestFixturePlugin
3. use the configure script to make your system basically functional from the browser
   • 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=
   • Make sure you have installed CPAN:Devel::Symdump module ( perl -MCPAN -e "install Devel::Symdump")
   • perl ../bin/TestRunner.pl TWikiSuite.pm
5. Run the TestCaseAmISane sanity check manual testcase
6. cd core and install the TestFixturePlugin perl pseudo-install.pl TestFixturePlugin
   • Do not enable TestFixturePlugin in configure
   • CPAN prerequisites: CPAN:HTML::Tagset CPAN:HTML::Parser ( perl -MCPAN -e "install HTML::Tagset" perl -MCPAN -e "install HTML::Parser" )
7. Run all the automatic testcases in the TestCases web (use firefox, and open each 'run' link in a new tab)
   • LOG IN FIRST (admin with configure pwd?)
   • Enable $TWiki::cfg{INCLUDE}{AllowURLs} = 1; in the Security settings | Miscellaneouss area of configure (must click Yes, I've read all the documentation button to see this expert setting first) 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/Contrib/core/DEPENDENCIES
lib/TWiki/Contrib/core/MANIFEST
lib/TWiki/Contrib/core/build.pl
lib/TWiki/Store/Subversive.pm
10. fix up TWikiReleaseNotes##x## topic with release date, release number and new changelogs - see
    • http://develop.twiki.org/~twiki4/cgi-bin/view/Bugs/ReleaseNotesTml?type=patch
11. fix up TWiki.WebHome topic to link to new TWikiReleaseNotes##x##
12. fix up TWiki.TWikiHistory topic with new dates - see
    • Appendix A: TWiki Development Time-line
13. Check that all doc topic have correct TOPICINFOs (3 topic changes above will need topicmeta fixed)
    • The following command should return zero results:
    • cd data; grep '%META:TOPICINFO{' */*.txt | grep -v TestCases | grep -v 'author="TWikiContributor".*version="\$Rev'
    • If needed, use the tools/fixtopicmeta to fix the META:TOPICINFO of topic
    • Example ../tools/fixtopicmeta TWiki/TWikiReleaseNotes05x00.txt
14. Check-in updated topics
    • Example svn commit -m "Item6711: Documentation work for TWiki 5.1.0"

Build a test release package

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

1. Install default plugins (hard copy)
   • cd core
   • 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
   • ./lib/TWiki.pm is updated with the release name by the build.pl script.
3. cd lib
4. perl ../tools/build.pl release
   • Note: if you specify a release name the script will attempt to commit to svn
   • Must change hardcoded item number to valid number in build.pl; search for: $cmd = "svn commit -m 'Item000: $tim' ../lib/TWiki.pm"

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. Send out a email to twiki-dev@listsPLEASENOSPAM.sourceforge.net asking that checkins be held for a few hours
2. Clean the build area again
   • cd branches/TWikiRelease05x01
   • svn status | grep '?' | sed 's/?/rm/' | sh
3. Install default plugins
   • cd core
   • perl pseudo-install.pl -link default to install the plugins specified in MANIFEST
4. use the configure script to make your system basically functional
5. cd lib
6. perl ../tools/build.pl release
   • please specify a release name (eg. 5.0.0-rc1, 5.0.1), and commit to svn
   • This will build the release package to branches/TWikiRelease05x01/core
   • Must change hardcoded item number to valid number in build.pl; search for: $cmd = "svn commit -m 'Item6711: $tim' ../lib/TWiki.pm"
7. re-package .tgz to follow standard to have everything in a twiki sub-directory; remove obsolete html files. Example for TWiki-5.1.0:
   • mkdir /tmp/repackage
   • mkdir /tmp/repackage/twiki
   • cp -p TWiki-5.1.0.tgz /tmp/repackage/twiki
   • cd /tmp/repackage/twiki
   • tar xfv TWiki-5.1.0.tgz
   • rm TWiki-5.1.0.tgz
   • cd ..
   • tar -pczf TWiki-5.1.0.tgz twiki
   • cd twiki
   • zip -r TWiki-5.1.0.zip *
   • mv *.zip ..
   • cd ..
   • md5sum TWiki-5.1.0.tgz TWiki-5.1.0.zip >TWiki-5.1.0.md5
8. Upload to TWiki:
   • Attach .tgz, .zip, .md5 to TWiki:Codev.Release
9. follow ProductionReleaseChecklist
10. For patch releases:
    • Create patch log - http://develop.twiki.org/~twiki4/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 5.0.0/ 5.0.2/ > TWiki-5.0.2-patch.diff
    • grep "+++ 5.0.2" TWiki-5.0.2-patch.diff > TWiki-5.0.2-filelist-changed.txt

Create a release tag

1. create an svn tag from the released version (you NEED to know the revision number that was committed when creating the final release package)
   svn copy -r *REV* http://svn.twiki.org/svn/twiki/branches/TWikiRelease05x01/ 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 (see note below on svn add) and and svn commit
   • Unpacking the .tgz release package creates twiki directory. So make sure to add history files in right place/directory. (One can do: mv core twiki; tar xvfz TWiki-5.1.0.tgz; mv twiki core;)
   • the ,v files are later used by the next release build. (and to track actually released files)
   • the ,v files are ignored by svn add * --force To resolve, cd to each directory under ./core/data and svn add *
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

• This does not apply to new patch releases

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/trunk/ http://svn.twiki.org/svn/twiki/branches/TWikiRelease*RELEASENAME_WITHOUTPATCHNUMBER*

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

Discussions

Some minor corrections above.

-- RichardDonkin - 28 Aug 2007

Small updates to the Build procedure for TWiki-5.0.X (manually) section as part of the 5.0.2 release prep

-- GeorgeTrubisky - 2011-04-27

small updates for 5.1.0 release prep

-- GeorgeTrubisky - 2011-07-18