Page History

Getting Ready

Setting up ssh

Create signing key

Get hold of RAT

Useful Resources

Incubator release best practice
Incubator Policy
ASF Developer Guide
ASF Release FAQ
ASF Release Licensing FAQ
ASF Release Signing
ASF Comitters Guide
Henk's ASF Key Guide
Surfnet Key Server
MIT Key Server
Raymond's release script

Release Reviewer Check List

Check that all RELEASE-NOTES and READMEs etc have the right release number and date
Check that the RAT output doesn't report missing or non-ASF licenses other than for files that can't have ASF licenses.
Check that all files (that need it) have the ASF copyright and it's the right date
Check that there are no SNAPSHOT dependencies still in the distribution
Check that the LICENSE and NOTICE files appear at the top level of each distributed aritfact

source distro
Check that the LICENSE and NOTICE files appear at the top level of binary distro
Check that the LICENSE and NOTICE files appear at the top level of all /maven modules that will be distributed (these are the tricky ones as they get copied when people add new modules)
Check that LICENSE

files have a copy of all third part

licenses for the files in directories below them (jar name and version to which

license relates

must be clearly marked. Use the list from the distribution lib dir

)

Check that NOTICE files have a copy of all of the copyright statements for the files in directories below the. You have to go through all dependency jars/files that have been copied in and check
Check that the signatures are in the right format

Check that

the signing key is in the KEYS file and in an external repo
Check that there are no SNAPSHOT dependencies still in the distribution
Check that there is no junk left in the distributions

(.log, .tmp, .bak etc)
Check that the distribution match the tag as far as possible.

(Our NOTICE files have the module name dropped in automatically

so don't match and we don't ship svg files)

Check that the manifests in the jars that we produce

have enough information

(name of product and version. Scripts below should do this

).
Check that the project depends on the smallest number of versions of each third party jar
Check that all samples compile and run from the command line and where appropriate operate correctly in Tomcat/WebSphere/Jetty/Geronimo
Check that all demos compile and run from the command line and where appropriate operate correctly in Tomcat/WebSphere/Jetty/Geronimo
Check to make sure Javadocs are generated for APIs and SPIs.

Release Manager Release Process

This page borrows many of the commands from Raymond's release script but with a bit more explanation and a few extra useful commands. The commands here were taken from when release 1.1 RC3a was under preparation. Note that this document has been updated from experience gained with the SDO 1.1.1 release, which was the first release made after exiting incubation; as such, whilst the release names used in this document refer to an "incubating" version, the svn repository and the maven repository have been updated to the non incubating versions. It's also fair to say that it's unlikely that you will want to run all of these commands in sequence as you generally end up repeating sections as release preparation progresses.

Call for release

At some point someone in the community will call for a release based on the features and fixes that have been under development in the trunk. Typically the first stage in the release process is to decide on who is going to be the release manager, i.e. who is going to ensure that all the steps are taken to ensure a good release. This will typical involve someone volunteering and a vote on the dev list.

Release Process

The borrows many of the commands from Raymond's release script but with a bit more explanation and a few extra useful commands. The commands here we taken from when release 1.1 RC3a was under preparation. It's also fair to say that it's unlikely that you will want to run all of these commands in sequence as you generally end up repeating sections as release preparation progresses.

Call for release

At some point someone in the community will call for a release based on the features and fixes that have been under development in the trunk. Typically the first stage in the release process is to decide on who is going to be the release manager, i.e. who is going to ensure that all the steps are taken to ensure a good release. This will typical involve someone volunteering and a vote on the dev list. The next thing is the create a branch where the code can be stabalized stabilized and testing can start on the release artifacts. It's useful to try and ensure that the code is complete as possible and that all the samples run before the branch is created. This removes the need for a lot of double fixing between the branch and the trunk.

Create the branch

   
svn copy https://svn.apache.org/repos/asf/incubator/tuscany/java/sca https://svn.apache.org/repos/asf/incubator/tuscany/branches/sca-java-1.1  -m "Branch for 1.1"

Once the branch is created the version number in trunk can be updated.

Fix up the branch work

First checkout the branch so that you can work on it. These commands assume that a local directory called "branches" is present.

 
cd branches
svn co https://svn.apache.org/repos/asf/incubatortuscany/tuscany/branches/sca-java-1.1/ 1.1-RC3a

Remove all the files that are not going to be part of the release, test all the samples and check all of the LICENSE and NOTICE files. Once the branch is at the stage where a release candidate can be created for testing prepare to make a tag.

Create Tag 1.1-RC3a

These commands assume that a local directory called "tags" is present.

 
cd tags
svn co https://svn.apache.org/repos/asf/incubator/tuscany/branches/sca-java-1.1/ 1.1-RC3a

Notice that all we are doing here is just checking out the branch again. This allows any last minute fixes to be taken from the branch in subversion and allows the version numbers in the tag to be corrected without affecting the branch, assuming that more than one tag will be required to complete the release process.

Change the version ID

The "-SNAPSHOT" is removed from the end of the version string. This ensures that the only thing building with the release version number on your PC is the tag being tested.

cd tags/1.1-RC3a
for i in `/usr/bin/find . -name "*.xml"`; do if grep 1.1-incubating-SNAPSHOT $i>/dev/null; then sed "s/1.1-incubating-SNAPSHOT/1.1-incubating/g" $i >/tmp/tmp.xml; cp /tmp/tmp.xml $i; fi; done

Generate the RAT report

Create the report.

cd tags
java -jar C:\simon\apps\rat-0.5.1\rat-0.5.1.jar 1.1-RC3a > rat-1.1-RC3a.txt

Copy the report up onto the staging repo. You should of course check the report at this stage.

scp rat-1.1-RC3a.txt slaws@people.apache.org:public_html/tuscany/1.1-RC3a

Build from top level

cd tags/1.1-RC3a 
mvn -o clean install

Build the demos

cd tags/1.1-RC3a/demos
mvn -fae -o clean install

Build distribution

cd tags/1.1-RC3a/distribution
mvn -o clean install

Check that the "all" jar is in place as with some JDKs this step fails intermittently

Copy the distribution to somewhere and try it

Try all the samples/demos

ant run

and

ant build
ant run

The war samples are currently to be tested with

• Tomcat 5.5.20 and Tomcat 6.0.14
• Jetty 6.1.3
• Geronimo 2.0.2 Tomcat6 jee5
• WebSphere 6.1 fix pack 9+

Clean you local repo of SCA modules and compile the source distro and run some samples to

Check for copyrights in the code to ensure that are what you are expecting

grep -iR Copyright *

check all the NOTICE files

for i in `find . -name NOTICE`; do echo XXXXXXXXXXXXXXXXXXXXXXXXXXXX; echo $i; cat $i; done > ../tmp

Check for any SNAPSHOTS left in by mistake

grep -r --include=*.xml SNAPSHOT *

Check the LICENSE file against what is provided in the distributions. There is no automation for this bit yet.

Check for junk included by accident

  find . -name log -print
  find . -name work -print
  find . -name lck -print
  find . -name activemq-data -print
  find . -name temp -print
  find . -name tmp -print

Once you are happy with the release artifacts you can sign them and make them available from review.

Sign the artifacts

Linux

.

Check dependencies are as you would expect them to be. In particular check that we aren't depending on many different versions of third part jars. If we are this has the side effect of messing up the generated build files. If module A depends on x.jar v1.2 and module B depends on x.jar v1.3 then when a build file that is generated for a sample that only depends on module A the stated x.jar dependency will be v1.2. Of course the distribution build will make sure that only v1.3 is actually shipped and so the ant build will fail. (TODO - need better automation)

cd sca
mvn -o -Pdependencies -Dmaven.test.skip=true
find . -name dependency.txt -exec cat '{}' >> deptotal.txt \;

or

cd sca
mvn dependency:tree

Use you favorite spreadsheet tool to open deptotal.txt and order on the first column to see across the project what dependencies we have on what libraries/versions.

Once the branch is at the stage where a release candidate can be created for testing prepare to make a tag.

svn merge -r 674473:674474 https://svn.apache.org/repos/asf/tuscany/tags/java/sdo/1.1.1-RC2a/ .

Create Tag 1.1-RC3a

These commands assume that a local directory called "tags" is present.

cd tags
svn co https://svn.apache.org/repos/asf/tuscany/branches/sca-java-1.1/ 1.1-RC3a

Notice that all we are doing here is just checking out the branch again. This allows any last minute fixes to be taken from the branch in subversion and allows the version numbers in the tag to be corrected without affecting the branch, assuming that more than one tag will be required to complete the release process.

Fix the release dates

In various files under distribution/src/main/release the month of release is quoted. Fix this to be the expected release month.

Check the notice dates

It's not clear what the policy for dates in notice files is currently. We have gone for the following...

Copyright (c) 2005 - 2009 The Apache Software Foundation

As the project moves forward we need to check that the last date matches the current year. If you need to change all the notice files here's a script

for i in `/usr/bin/find . -name "NOTICE"`; do sed "s/Copyright (c) 2005 - 2008/Copyright (c) 2005 - 2009/g" $i >/tmp/tmp.notice; cp /tmp/tmp.notice $i; done

Change the version ID

The "-SNAPSHOT" is removed from the end of the version string. This ensures that the only thing building with the release version number on your PC is the tag being tested.

cd tags/1.1-RC3a
for i in `/usr/bin/find . -name "*.xml" -o -name "*.java"`; do if grep 1.3-SNAPSHOT $i>/dev/null; then sed "s/1.3-SNAPSHOT/1.3/g" $i >/tmp/tmp.xml; cp /tmp/tmp.xml $i; fi; done

Generate the RAT report

Create the report.

cd tags
java -jar C:\simon\apps\rat-0.5.1\rat-0.5.1.jar 1.1-RC3a > rat-1.1-RC3a.txt

Copy the report up onto the staging repo. You should of course check the report at this stage.

scp rat-1.1-RC3a.txt slaws@people.apache.org:public_html/tuscany/1.1-RC3a

Build from top level

cd tags/1.1-RC3a
mvn -o clean install

cd tags/1.1-RC3a/demos
mvn -fae -o clean install

cd tags/1.1-RC3a/tutorial
mvn -fae -o clean install

Build distribution

cd tags/1.1-RC3a/distribution
mvn -o clean install

Check that the "all" jar is in place as with some JDKs this step fails intermittently

Copy the distribution to somewhere and try it

Try all the samples/demos

ant run

and

ant build
ant run

The war samples are currently to be tested with

• Tomcat 5.5.20 and Tomcat 6.0.14
• Jetty 6.1.3
• Geronimo 2.0.2 Tomcat6 jee5
• WebSphere 6.1 fix pack 9+

Clean you local repo of SCA modules and compile the source distro and run some samples to

Check for copyrights in the code to ensure that are what you are expecting

grep -iR --exclude=LICENSE --exclude=NOTICE Copyright * | awk '{if (!match($0, ".+ASF.+")) {print $0}}'

check all the NOTICE files

for i in `find . -name NOTICE`; do echo XXXXXXXXXXXXXXXXXXXXXXXXXXXX; echo $i; cat $i; done > ../tmp

Check for any SNAPSHOTS left in by mistake

grep -r --include=*.xml SNAPSHOT *

Check the LICENSE file against what is provided in the distributions. There is no automation for this bit.

Check that all jars in the distribution\lib is mentioned on the binary LICENSE

for fn in *.jar; do if grep -q $fn ../LICENSE; then "$fn"; else "$fn NOT present"; fi; done

For 2.x this is

for fn in `find . -name "*.jar" -printf "%f\n"`; do if grep -q $fn ../LICENSE; then "-"; else "$fn NOT present"; fi; done;

And check that all jars that are mentioned are present

for fn in `awk '/.jar/ {if (match($0,"[a-zA-Z0-9._-]+[.]jar")) {print substr($0, RSTART,RLENGTH) } }' ../LICENSE`; do if ls | grep -q $fn; then echo "$fn";else echo ">>> $fn NOT present"; fi; done

For 2.x this is

for fn in `awk '/.jar/ {if (match($0,"[a-zA-Z0-9._-]+[.]jar")) {print substr($0, RSTART,RLENGTH) } }' ../LICENSE`; do if ls * | grep -q $fn; then echo "-";else echo ">>> $fn NOT present"; fi; done

Check for junk included by accident

  find . -name log -print
  find . -name work -print
  find . -name lck -print
  find . -name activemq-data -print
  find . -name temp -print
  find . -name tmp -print

Once you are happy with the release artifacts you can sign them and make them available for review.

Sign the artifacts

Linux

cd tags/1.1-RC3a/distribution/target
for i in *.zip *.gz; do gpg --output $i.asc --detach-sig --armor $i; done
for i in *.zip *.gz; do openssl md5 -hex $i | sed 's/MD5(\([^)]*\))= \([0-9a-f]*\)/\2 *\1/' > $i.md5; done

Windows:

for %A in (*.zip) do gpg --output %A.asc --detach-sig --armor %A
for %A in (*.gz) do gpg --output %A.asc --detach-sig --armor %A
for %A in (*.zip) do gpg --print-md md5 %A > %A.md5
for %A in (*.gz) do gpg --print-md md5 %A > %A.md5

The commands above should produce artifacts of an appropriate format, as follows.

md5 should look like

  8fb7cb398063ed0dffa414168468fffc *apache-tuscany-sca-1.1-incubating.zip

asc should look like

-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.5 (Cygwin)

iD8DBQBHnLGGE8fTrnkHPxIRAqPmAJ4tOR6W663FKCXHPi1GlLBWDyZwJgCeMqbb
68DOq0YsU/O7kJsBHuZXhJw=
=elh0
-----END PGP SIGNATURE-----

Also you now need to sign the jars in the Eclipse update site.

cd to both plugins and features and run:

cd tags/1.1-RC3a/distribution/target/apache-tuscany-sca-<releasenum>-updatesite.dir/tuscany-sca-<releasenum>-updatesite/plugins
for i in *.jar; do gpg --output $i.asc --detach-sig --armor $i; done
for i in *.jar; do openssl md5 -hex $i | sed 's/MD5(\([^)]*\))= \([0-9a-f]*\)/\2 *\1/' > $i.md5; done
cd ../features
for i in *.jar

cd tags/1.1-RC3a/distribution/target
for i in *.zip *.gz; do gpg --output $i.asc --detach-sig --armor $i; done
for i in *.zip *.gzjar; do openssl md5 -hex $i | sed 's/MD5(\([^)]*\))= \([0-9a-f]*\)/\2 *\1/' > $i.md5; done

Windows:And then sign site.xml in the top level of the updatesite directory

cd ..
for %Ai in (*.zip)xml; do gpg --output %A$i.asc --detach-sig --armor $i; %Adone
for %Ai in (*.gz)xml; do gpg --output %A.asc --detach-sig --armor %A
for %A in (*.zip) do gpg --print-md md5 %A > %A.md5
for %A in (*.gz) do gpg --print-md md5 %A > %A.md5

The commands above should produce artifacts of an appropriate format, as follows.

md5 should look like

  8fb7cb398063ed0dffa414168468fffc *apache-tuscany-sca-1.1-incubating.zip

asc should look like

-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.5 (Cygwin)

iD8DBQBHnLGGE8fTrnkHPxIRAqPmAJ4tOR6W663FKCXHPi1GlLBWDyZwJgCeMqbb
68DOq0YsU/O7kJsBHuZXhJw=
=elh0
-----END PGP SIGNATURE-----

openssl md5 -hex $i | sed 's/MD5(\([^)]*\))= \([0-9a-f]*\)/\2 *\1/' > $i.md5; done

Put the artifacts up in your home directory on people.apache.org

cd tags/1.1-RC3a/distribution/target
scp *.asc slaws@people.apache.org:public_html/tuscany/1.1-RC3a
scp *.md5 slaws@people.apache.org:public_html/tuscany/1.1-RC3a
scp *.zip slaws@people.apache.org:public_html/tuscany/1.1-RC3a
scp *.gz slaws@people.apache.org:public_html/tuscany/1.1-RC3a

cd tags/1.1-RC3a/distribution/target/apache-tuscany-sca-<releasenum>-updatesite.dir
scp -r *.asc slaws@people.apache.org:public_html/tuscany/1.1-RC3a

scp *.md5 slaws@people.apache.org:public_html/tuscanycd tags/1.1-RC3a/distribution/src/main/release
scp *.zipRELEASE_NOTES slaws@people.apache.org:public_html/tuscany/1.1-RC3a
scp *.gzCHANGES slaws@people.apache.org:public_html/tuscany/1.1-RC3a

Check permissions on the files

cd tags/1.1-RC3a/distribution/src/main/release
scp RELEASE_NOTES slaws@people.apache.org:public_html/tuscany/1.1-RC3a
scp CHANGES slaws@people.apache.org:public_html/tuscany/1.1-RC3a

Check permissions on the files

chmod 644 *.zip
chmod 644 *.gz
chmod 644 *.txt

chmod 644 *.zip
chmod 644 *.gz
chmod 644 *.txt

Deploy the maven artifacts

Note below that the reference to "apache.incubator" in the "id" part of the -DaltDeploymentRepository argument to the maven deploy plugin is simply an identifier relating to a stanza in your local maven repo's settings.xml file. Note that also if you use ssh authentication by referencing a file containing your private key from the settings.xml file, then be sure to use a file in open ssh format.  People who have followed the apache instructions for creating ssh keys on Windows with putty will probably not have created open ssh format files. You can however convert your .ppk file to the open ssh forrmat by loading it into puttygen and using the conversion menu.

cd tags/1.1-RC3a
mvn -N -DaltDeploymentRepository=apache.incubator::default::scp://people.apache.org/home/slaws/public_html/tuscany/1.1-RC3a/maven verifyinstall gpg:sign install:install deploy:deploy -Dgpg.passphrase=

cd tools
mvn clean
mvn -DaltDeploymentRepository=apache.incubator::default::scp://people.apache.org/home/slaws/public_html/tuscany/1.1-RC3a/maven verifyinstall gpg:sign install:install deploy:deploy -Dgpg.passphrase=

cd modules
mvn clean
mvn -DaltDeploymentRepository=apache.incubator::default::scp://people.apache.org/home/slaws/public_html/tuscany/1.1-RC3a/maven verifyinstall gpg:sign install:installsign deploy:deploy -Dgpg.passphrase=

NOTE:Remove non jar artifacts from stage repo

Deploy the all jar

cd tags/1.1-RC3a/distribution/bundle/target
mvn gpg:sign-and-deploy-file -DgroupId=org.apache.tuscany.sca -DartifactId=tuscany-sca-all -Dversion=1.1-incubating -Dpackaging=jar -Dfile=tuscany-bundle-1.1-incubating.jar -DrepositoryId=apache.incubator -Durl=scp://people<userid@>people.apache.org/home/slaws/public_html/tuscany/1.1-RC3a/maven -Dkeyname=slaws -Dpassphrase=

I have to go in and sign the pom for the all jar manually as it didn't happen automatically?

Check that the Maven artifacts work

Point you maven build at your p.a.o dir as a temporary mirror, for example, add mirror element to the settings.xml file (usually found at .m2/settings)

  <mirrors>
   <mirror>
     <id>ant.staging</id>
     <url>http://people.apache.org/~slaws/tuscany/1.1-RC3a/maven</url>
     <mirrorOf>apache.incubator</mirrorOf>
   </mirror>
  </mirrors>

Clean you your local SCA artifacts and use maven to compile samples and see if they run.

Check in the tag

svn copy 1.1-RC3a https://svn.apache.org/repos/asf/incubator/tuscany/tags/java/sca/1.1-RC3a/ -m "Tag for 1.1-RC3a"

Start voting

The PPMC will vote first. This may give rise to a new release candidate being required. If so you need to go back and start at the "Create Tag" step but using the next RC number.

Once the PPMC vote is complete the vote is moved across to the IPMC. Once all the votes are complete the artifacts that have been voted on can be release.

Once all the

voting is complete

Copy the artifacts from your directory on people.apache.org to:

Code Block
/www/www.apache.org/dist/tuscany/java/sca/1.3.2

except for the tuscany-sca-<releasenum>-updatesite-publish directory. The contents of this directory should be checked into svn under:

Code Block
https://svn

Once all the voting is complete

.apache.org/

repos/

asf/tuscany

/site/trunk/site-publish/updatesite/java/sca/<releasenum>

Also check that the KEYS file is up to date.

scp KEYS slaws@people/www/www.apache.org:public_html/dist/tuscany/1.1-RC3a

Copy the staging repo to the live

repo

mvn stage:copy -Dsource="http://people.apache.org/~slaws/tuscany/1.1-RC3a/maven" -Dtarget="scp://people<userid@>people.apache.org/www/people.apache.org/repo/m2-ibiblio-incubatingrsync-repository" -Dversion=1.1

You'll need the maven stage plugin to do this. Since maven-stage-plugin is not published, the release manager should checkout the source for the plugin and build it.for the plugin and build it.

http://svn.apache.org/repos/asf/maven/plugins/trunk/maven-stage-plugin/

Or, instead of using the Maven stage plugin just manually copy the artifacts there:

cp -p -v -R  sca/  /x1/www/people

http://svn.apache.org/repos/asf/maven/plugins/trunk/maven-stage-plugin/repo/m2-ibiblio-rsync-repository/org/apache/tuscany/sca

Check the permissions in the repo

There is a script in the SNAPSHOT report that sets the permissions correctly.

cd  /www/people.apache.org/repo/m2-ibiblio-incubatingrsync-repository/org/apache
/tuscany/sca]
/www/people.apache.org/repo/m2-snapshot-repository/fix-permissions.sh

Copy the release candidate tag to the final tag name.

svn copy https://svn.apache.org/repos/asf/incubator/tuscany/tags/java/sca/1.1-RC3a/ https://svn.apache.org/repos/asf/incubator/tuscany/tags/java/sca/1.1 -m "Copy 1.1-RC3a tag as 1.1"