Exercise 04: Publishing

What This Exercise Is About

Having a successful build is only the first part of the release engineering experience. Consistently publishing your builds every week is part of good project health, and doing so in an automated fashion is important for good release engineer health.

What You Should Be Able To Do

At the end of the lab, you should be able to:

Required Materials

Recommended Materials

Exercise Instructions

This exercise is carried out entirely using the Eclipse Software Development Kit (SDK) version 3.4M5 with the Eclipse Modeling Framework (EMF) 2.4M5 installed into it. The exercise instructions refer to this product as either Eclipse or as "the workbench."

These instructions are located in your workspace, in the Build_Workshop/Exercise04_Publishing folder.

Directions

Step A: Setup

  1. Switch to the Plug-in Development perspective, if not already there.
    1. Select Window -> Open Perspective -> Other... -> Plug-in Development.
  2. In the Package Explorer view, right-click the file Build_Workshop\Exercise04_Publishing\exercise_04.psf and select Import Project Set.... If prompted to overwrite, click Yes To All.
  3. If you prefer, you can also use the Import -> Existing Projects into Workspace method from Exercises 01 and 02, using Solution04.zip.

Step B: Configure Promote Page

  1. There are two files that control how builds are published (promoted) to the production server from the build server.
  2. The first file is _common.php, shared by both the build (build/index.php) and promote (build/promo.php) pages.
    1. Open www-modeling/m2t/jet/build/_common.php and review its contents.
    2. You will see a list of versions that can be built, the CVS branches that map to those versions, and the JDK path and version to use.
    3. You will also see default email address(es), comma-separated, which will be used to prepopulate the build and promote pages. In the event of a build failure, these email address(es) will also be used to alert people to a possible problem.
    4. Finally, you will see an array of usernames. Generally, the first two are the same, eg., nickb. The last one is used for an internal CVS, and should usually be NULL.
  3. To learn more about how a build or promote is controlled, open build/index.php or build/promo.php, respectively, then follow the includes & requires to the actual heart of the script, eg., www-modeling/build/build-common.php and www-modeling/build/promo-common.php.
  4. Basically, these two pages are wrappers to shell scripts. Each one collects data input by the user and the _common.php arrays, and collates that into a build or promote script command.
  5. Here's an example of a build command, as generated by the build page: 
    mkdir -p /home/www-data/build/modeling/m2t/jet/downloads/drops/0.9.0/N200803131953/eclipse;
/bin/bash
 -c "exec /usr/bin/nohup /usr/bin/setsid 
 /home/www-data/build/modeling/scripts/start.sh
 -proj m2t
 -sub jet
 -version 0.9.0
 -branch HEAD
 -URL http://download.eclipse.org/eclipse/downloads/drops/S-3.4M5-200802071530/eclipse-SDK-3.4M5-linux-gtk.tar.gz
 -URL http://emf.torolab.ibm.com/modeling/emf/emf/downloads/drops/2.4.0/S200802090050/emf-sdo-xsd-SDK-2.4.0M5.zip
 -antTarget run
 -buildAlias 0.9.0M5
 -mapfileRule use-false
 -buildType N
 -javaHome /opt/sun-java2-5.0
 -downloadsDir /home/www-data/build/downloads
 -buildDir /home/www-data/build/modeling/m2t/jet/downloads/drops/0.9.0/N200803131953
 -writableBuildRoot /home/www-data
 -buildTimestamp 200803131953
 -email nickboldt@gmail.com
 -basebuilderBranch M5_34 >> 
 /home/www-data/build/modeling/m2t/jet/downloads/drops/0.9.0/N200803131953/buildlog.txt 2>&1 &"
  6. And here's an example of a promote command -- note the items that are controlled by the webpage which appear as commandline switches: 

    mkdir -p /home/www-data/promo_logs/;
/bin/bash
 -c "exec /usr/bin/nohup /usr/bin/setsid ssh build@buildbox.torolab.ibm.com 
 \"cd /home/www-data/build/modeling/scripts; ./promoteToEclipse.sh
 -c org.eclipse.m2t/org.eclipse.jet.releng/promoteToEclipse.jet.properties,HEAD
 -Q
 -cvsbranch HEAD
 -branch 0.9.0
 -buildID S200802121745
 -user build
 -addSDK /home/www-data/build/requests/dependencies.urls.txt
 -noIES
 -announce
 -coordsite ganymede
 -email nickboldt@gmail.com \" >> 
 /home/www-data/promo_logs/promo_log_jet_0.9.0.S200802121745_2008-03-13-19.55.40.txt 2>&1 &"
  7. In the second example, note the -c command switch, which defines which properties file to use, and from which branch of CVS.

Step B: Configure Promote Script

  1. Only a small fraction of the configuration options are present on the promote page, because very few need to be exposed for weekly use. For the properties that need to be set once a release cycle (eg., 1-3 times a year), a properties file is used instead.
    1. Open org.eclipse.jet.releng/promoteToEclipse.jet.properties and review its contents.
  2. Some of the more noteworthy items include the newsgroup* properties, the 0/1 properties, and the branch properties. 
    # publisher of newsgroup announcements
newsgroupPublisherEmail="Nick Boldt <codeslave@ca.ibm.com>"
newsgroup=eclipse.modeling.$projectName
# to thread posts under an existing post (or posts) enter the slash-escaped 
# Message-ID for which this is a reply,
# eg: <du7hic\$qos\$1@utils.eclipse.org>
newsgroupThreadReferences="<f0qmc9\$abo\$1@build.eclipse.org>"

# default setting for whether to do or skip the drop upload section: 0 = do, 1 = skip
dodrop=1
# default setting for whether to do or skip the javadoc section: 0 = do, 1 = skip
dodocs=1
# default setting for whether to do or skip the Update Manager jars section: 0 = do, 1 = skip
UMjars=1
#do RSS feed file update?
RSS=1

branch=0.9.0
cvsbranch=HEAD
  3. Using the History view, you can compare this file with previous or branched versions to see how its contents evolve.
  4. To see how these properties are used, open releng-common-tools-scripts/promoteToEclipse.sh and review its contents, searching for matching variables & flags (eg., newsgroupThreadReferences or -announce).

Summary

You have learned how to configure both the commandline scripts and web UI for promoting your builds. Next, we'll explore some of the problems that can occur.