Tags:
build3Add my vote for this tag ci1Add my vote for this tag development2Add my vote for this tag process1Add my vote for this tag create new tag
, view all tags

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 open source 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 lib/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-6.0.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/TWikiRelease06x00
    • 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:
    • 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
  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 the $RELEASE in lib.TWiki.pm and the $VERSION in lib/TWiki/Plugins.pm to match the release. lib/TWiki/Func.pm and EmptyPlugin's lib/TWiki/Plugins/EmptyPlugin.pm may refer to the version/release number as well, which need to be updated if necessary.
    By convention, Major.MinorPatch is used, without a dot between Minor and Patch. For example, for TWiki-6.1.3 release, $VERSION will be 6.13
  11. Fix up TWikiReleaseNotes06x00 topic with release date, release number and new changelogs - see
  12. Fix up TWiki.WebHome topic to link to new TWikiReleaseNotes06x00
  13. Fix up TWiki.TWikiHistory topic with new dates - see
    • Appendix A: TWiki Development Time-line
  14. Fix up TWiki.TWikiInstallationGuide topic with new version numbers
  15. Fix up TWiki.TWikiUpgradeGuide topic with new version numbers, and add a new "Important Changes since TWiki-6.0.2" section
  16. 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/TWikiReleaseNotes06x00.txt
  17. Check-in updated topics
    • Example svn commit -m "Item7698: Documentation work for TWiki-6.0.2"

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. Make a build
    • perl pseudo-install.pl BuildContrib to install the code needed for build
    • cd lib
    • 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 'Item7698: $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/TWikiRelease06x00
    • 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
    • perl pseudo-install.pl BuildContrib to install the code needed for build
  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. 6.0.2-rc1, 6.0.8), and commit to svn
    • This will build the release package to branches/TWikiRelease06x00/core
    • Must change hardcoded item number to valid number in build.pl; search for: $cmd = "svn commit -m 'Item7698: $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-6.0.2:
    • mkdir /tmp/repackage
    • mkdir /tmp/repackage/twiki
    • cp -p TWiki-6.0.2.tgz /tmp/repackage/twiki
    • cd /tmp/repackage/twiki
    • tar xzvf TWiki-6.0.2.tgz
    • rm TWiki-6.0.2.tgz
    • cd ..
    • tar -pczf TWiki-6.0.2.tgz twiki
    • cd twiki
    • zip -r TWiki-6.0.2.zip *
    • mv *.zip ..
    • cd ..
    • md5sum TWiki-6.0.2.tgz TWiki-6.0.2.zip >TWiki-6.0.2.md5
  8. Upload to TWiki:
    • Attach .tgz, .zip, .md5 to TWiki:Codev.Release
    • 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. Example:
      • mkdir 6.0.1
      • mkdir 6.0.2
      • cd 6.0.1
      • tar xfv ../TWiki-6.0.1.tgz
      • cd ..
      • cd 6.0.2
      • tar xfv ../TWiki-6.0.2.tgz
      • cd ..
      • diff --ignore-all-space --ignore-blank-lines --unified --recursive --new-file 6.0.1/ 6.0.2/ > TWiki-6.0.2-patch.diff
      • grep "+++ 6.0.2" TWiki-6.0.2-patch.diff > TWiki-6.0.2-filelist-changed.txt
      • Attach patch.diff and filelist-changed.txt to TWiki:Codev.Release
  9. Locally install TWiki from archives above and smoke test
  10. follow ProductionReleaseChecklist

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). Example:
    svn copy -m 'Item7698: Create release tag for TWiki 6.0.2' -r REV http://svn.twiki.org/svn/twiki/branches/TWikiRelease06x00/ http://svn.twiki.org/svn/twiki/tags/TWikiRelease06x00x02
  2. checkout that new tag. Example:
    cd svn; mkdir tags/TWikiRelease06x00x02; cd tags/TWikiRelease06x00x02; svn co http://svn.twiki.org/svn/twiki/tags/TWikiRelease06x00x02/core
  3. Add release history and extension topics and then commit
    • Unpack the .tgz release package which creates twiki directory
      • mv core twiki
      • tar xvfz TWiki-6.0.2.tgz
      • mv twiki core
    • Add history files and extension topic files to SVN
      • cd core/data
      • for i in [A-Z]*; do (cd $i; svn add *) done
        • You see warnings of '*.txt' already under version control with topics included in the core package
        • the ,v files are later used by the next release build. (and to track actually released files)
    • Commit the changes
      • cd ..
      • svn ci -m 'Item7698: Add topics with release history to TWiki 6.0.2 tag'
  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 -m 'Item7698: Create branch for TWiki-6.0' -r *REV* http://svn.twiki.org/svn/twiki/trunk/ http://svn.twiki.org/svn/twiki/branches/TWikiRelease06x00
  • Do a shell login to develop.twiki.org and edit /home/svn/httpaccess.conf to lock donw previous branch and open up new branch. Not sure if Apache restart is needed, do it just in case.

-- 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

updated for CPAN prerequisites; patch release instructions; examples updated for 5.1.2

-- GeorgeTrubisky - 2012-10-07

I replaced hard coded version numbers with preferences settings (located in an HTML comment at the beginning). This makes it easier to update the doc for a new release.

-- Peter Thoeny - 2013-09-16

As per KampalaReleaseMeeting2014x11x06, we should consider:

  • Making the build process less manual
  • Making the build process quicker by checking out only modules needed for a release rather than the entire trunk or a release branch
These are interest of the builder, so the person who work on release building next may work on those.

-- Hideyo Imazu - 2014-11-07

I've update the "Create a new release tag" section. The points are: 1) checking out only core rather than the entire tags/TWikiRelease06x00x02, the time it takes for checking out is reduced a lot; 2) made the step 3 more explicit

-- Hideyo Imazu - 2016-01-28

Edit | Attach | Watch | Print version | History: r120 < r119 < r118 < r117 < r116 | Backlinks | Raw View | Raw edit | More topic actions
Topic revision: r120 - 2016-01-28 - HideyoImazu
 
  • Learn about TWiki  
  • Download TWiki
This site is powered by the TWiki collaboration platform Powered by Perl Hosted by OICcam.com Ideas, requests, problems regarding TWiki? Send feedback. Ask community in the support forum.
Copyright © 1999-2017 by the contributing authors. All material on this collaboration platform is the property of the contributing authors.