Page History

Procedure

1. Whenever possible, use the maven release plugin. If something doesn't work file a bug against it.
2. Use extreme caution in creating branches as opposed to releasing from trunk. While "core" geronimo may need to keep branches, most smaller projects such as specs, plugins, components, and most likely tools should avoid the complexity of branches unless clearly necessary and agreed upon.
3. When branches are needed, branches/x.y would be the branch for all x.y.z releases

The next sections are copied from http://maven.apache.org/developers/release/releasing.html with modifications for Geronimo.

Releasing A Geronimo Project

What follows is a description of releasing a Geronimo project to a staging repository, whereupon it is scrutinized by the community, approved, and transfered to a production repository.
Prerequisite

...

        <profile>
            <id>release</id>

            <build>
                <plugins>
                    
                    <plugin>
                        <groupId>org.apache.maven.plugins</groupId>
                        <artifactId>maven-release-plugin</artifactId>
                        <configuration>
                            <useReleaseProfile>false</useReleaseProfile>
                            <goals>deploy</goals>
                            <arguments>-Prelease</arguments>
                        </configuration>
                    </plugin>

                    <!-- We want a source jar -->
                    <plugin>
                        <groupId>org.apache.maven.plugins</groupId>
                        <artifactId>maven-source-plugin</artifactId>
                        <executions>
                            <execution>
                                <goals>
                                    <goal>jar</goal>
                                </goals>
                            </execution>
                        </executions>
                    </plugin>

                    <!-- We want to sign the artifact, the POM, and all attached artifacts -->
                    <plugin>
                        <groupId>org.apache.maven.plugins</groupId>
                        <artifactId>maven-gpg-plugin</artifactId>
                        <inherited>true</inherited>
                        <configuration>
                            <passphrase>${gpg.passphrase}</passphrase>
                        </configuration>
                        <executions>
                            <execution>
                                <goals>
                                    <goal>sign</goal>
                                </goals>
                            </execution>
                        </executions>
                    </plugin>

                    <!-- We want to deploy the artifact to a staging location for perusal -->
                    <plugin>
                        <groupId>org.apache.maven.plugins</groupId>
                        <artifactId>maven-deploy-plugin</artifactId>
                        <inherited>true</inherited>
                        <configuration>
                            <altDeploymentRepository>${deploy.altRepository}</altDeploymentRepository>
                            <updateReleaseInfo>true</updateReleaseInfo>
                        </configuration>
                    </plugin>

                    <!-- We want the JavaDoc JAR published with the release -->
                    <plugin>
                        <groupId>org.apache.maven.plugins</groupId>
                        <artifactId>maven-javadoc-plugin</artifactId>
                        <inherited>true</inherited>
                        <configuration>
                            <source>1.5</source>
                        </configuration>
                        <executions>
                            <execution>
                                <id>attach-javadocs</id>
                                <goals>
                                    <goal>jar</goal>
                                </goals>
                            </execution>
                        </executions>
                    </plugin>
                </plugins>
            </build>
        </profile>

Release Process for Part Of Geronimo

1. Prepare your poms for release:
Genesis and the recommended settings.xml file above rely on the existence of some configuration in the top level pom in your project to parameterize where in your staging area the release will be located. This makes it so you can have multiple independent releases under vote in your staging area at once, and clearly locates the maven generated site in the documentation once the release is completed. You should only need to do this the first time these instructions are used.

...

14. Add the release to the next board report, in the private subversion area.
15. Add the release to the wiki, under the Recent Releases section of the front page and on the Releases page.
16. Celebrate :o)

Notes and Gotchas

• If the selection of modules for the default build is set in a default profile then more work will be necessary. When genesis did not have the modules specified in the base pom this involved running mvn release:perform -Pdefault,release which only deploys the root, then running mvn deploy -Prelease in each of the 3 modules listed in the default profile. For projects that are not expected to be used as parents of independently releasable projects (for instance server/trunk) including the list of modules in the release profile override should work. Better still is just having the modules outside a profile.

When using the maven release plugin is impossible (this should be a less frequent event as we progress):

1. when a release is frozen, we spin off a branch with that exact name, as in branches/x.y.z, where z starts at zero and increments by one.
2. at that time branches/x.y is immediately updated to version x.y.(z+1)-SNAPSHOT
3. We cut releases from the frozen branch
4. When a release passes final tck testing and final vote, the frozen branch is moved to tags

Updating the poms after making a new branch

Once a new branch is created you will generally need to manage the version number in the poms. The following Perl scripts will assist in that task. It could use some polishing but given the relatively infrequent use.

...

Rationale

We create a branch at freeze time for the following reasons:

1. it takes at least one week from freeze to ship due to voting, tck testing and potential repeats of that process (re-cut, re-certify, re-vote). There is no reason why work on x.y.z+1 needs to be delayed - only 52 weeks a year.
2. stronger guarantee no one is updating the branch once frozen
3. less likely that people and ci systems (continuum) will checkout and build pre-release versions of x.y.z (not x.y.z-SNAPSHOT) which would need to be removed manually and may accidentally be distributed.
4. it is currently very difficult to roll version numbers forward, entries here and there are often missed. Far better to have branches/x.y have a few straggling old x.y.z-SNAPSHOT versions than a few overlooked x.y.z final numbers that needed to go back to SNAPSHOT - they never leave SNAPSHOT and need to be reverted back later if that process happens in the frozen branch.

Steps

1. Download and install the Gnu Privacy Guard (GPG) from http://www.gnupg.org. Read the documentation on that site and create a key. Have the key signed and verified by others. Submit your public key to http://pgp.mit.edu/. This is a one time process.
2. Create a "staging" profile in your ~/.m2/settings.xml

   Code Block
   <profile> <id>staging</id> <properties> <!-- deploy.altRepository>prasad::default::scp://people.apache.org/x1/home/prasad/public_html/2.0-M1-rc1</deploy.altRepository --> <deploy.altRepository>prasad::default::file://c:\cygwin\home\prasad\releases</deploy.altRepository> <gpg.passphrase>Your GPG Passphrase</gpg.passphrase> </properties> </profile>

3. Copy (or move as per situation, for eg specs) the trunk to branches using the following command.

   No Format
   svn mv SRC-URL DEST-URL -m "Reason for this commit".

4. Checkout or update this branches tree on your machine.
5. Update the <scm> urls in the pom.xml to point to the final url in tags. Eg:

   Code Block
   <scm> <connection>scm:svn:http://svn.apache.org/repos/asf/geronimo/specs/tags/geronimo-servlet_2.5_spec-1.1</connection> <developerConnection>scm:svn:https://svn.apache.org/repos/asf/geronimo/repos/asf/geronimo/specs/tags/geronimo-servlet_2.5_spec-1.1</developerConnection> <url>http://svn.apache.org/viewvc/geronimo/repos/asf/geronimo/specs/tags/geronimo-servlet_2.5_spec-1.1</url> </scm>

6. Build the new branches tree that will soon be released using the following command.

   No Format
   mvn -Pdefault,staging deploy

7. Go the temporary staging directory specified by deploy.altRepository element in the staging profile of your settings.xml. Delete all *.asc.* files under this directory tree. Tar the staging directory using the command

   No Format
   find . -name *.asc.* | xargs rm -f tar -zcvf release.tar.gz releases

8. Copy the tar ball to a publicly accessible location. Put it for a vote. In the vote notice, please include the precise names and versions being voted on (e.g. geronimo-javamail_1.4_spec-1.1) and the svn urls to the current source and where the tag will be created.
9. After it has been approved, untar the tar ball into the appropriate maven structure on people.apache.org under the directory /www/people.apache.org/repo/m2-ibiblio-rsync-repository. A cron job will rsync this with ibiblio and release it into the wild.

   No Format
   gunzip foo.tar.gz tar -xvf foo.tar

   Info
   Ensure that the files you copy to the rsync directory have 0775 dir permission and a 0664 file permission set on them.

10. Move the branches to tags using the following command.

    No Format
    svn mv SRC-URL DEST-URL -m "Reason for this commit".

Modified process used for Geronimo 2.1.1:

This incorporates some aspects of the maven release process but stops short of actually using the maven release plugin. Like the non-maven process it utilizes a branch for the release process.

1. when a release is frozen, we spin off a branch with that exact name, as in branches/x.y.z, where z starts at zero and increments by one.
2. at that time branches/x.y is immediately updated to version x.y.(z+1)-SNAPSHOT
3. We cut releases from the frozen branch
4. When a release passes final tck testing and final vote, the frozen branch is moved to tags

Updating the poms after making a new branch

Once a new branch is created you will generally need to manage the version number in the poms. The following Perl scripts will assist in that task. It could use some polishing but given the relatively infrequent use.

...

Rationale

We create a branch at freeze time for the following reasons:

1. it takes at least one week from freeze to ship due to voting, tck testing and potential repeats of that process (re-cut, re-certify, re-vote). There is no reason why work on x.y.z+1 needs to be delayed - only 52 weeks a year.
2. stronger guarantee no one is updating the branch once frozen
3. less likely that people and ci systems (continuum) will checkout and build pre-release versions of x.y.z (not x.y.z-SNAPSHOT) which would need to be removed manually and may accidentally be distributed.
4. it is currently very difficult to roll version numbers forward, entries here and there are often missed. Far better to have branches/x.y have a few straggling old x.y.z-SNAPSHOT versions than a few overlooked x.y.z final numbers that needed to go back to SNAPSHOT - they never leave SNAPSHOT and need to be reverted back later if that process happens in the frozen branch.

Steps

1. Download and install the Gnu Privacy Guard (GPG) from http://www.gnupg.org. Read the documentation on that site and create a key. Have the key signed and verified by others. Submit your public key to http://pgp.mit.edu/. This is a one time process.
2. Be sure that you have your ~/.m2/settings.xml updated as specified above in Releasing A Geronimo Project
3. Copy (or move as per situation, for eg specs) the trunk/branch to the new branch using the following command.

   No Format
   svn mv SRC-URL DEST-URL -m "Reason for this commit".

4. Checkout or update this branches tree on your machine.
5. Update the <scm> urls in the pom.xml to point to the final url in tags. Eg:

   Code Block
   <scm> <connection>scm:svn:http://svn.apache.org/repos/asf/geronimo/specs/tags/geronimo-servlet_2.5_spec-1.1</connection> <developerConnection>scm:svn:https://svn.apache.org/repos/asf/geronimo/repos/asf/geronimo/specs/tags/geronimo-servlet_2.5_spec-1.1</developerConnection> <url>http://svn.apache.org/viewvc/geronimo/repos/asf/geronimo/specs/tags/geronimo-servlet_2.5_spec-1.1</url> </scm>

6. Add the following release profile to the root pom.xml (Note: This is a subset of the profile included in the maven release process above). This will utilize the maven gpg plugin to sign the artifacts produced and the maven deploy plugin to stage the release to your people.apache staging location but will not utilize the maven release plugin to create the tag, rename versions, etc...

   Code Block

   <profile> <id>release</id> <build> <plugins> <!-- We want to sign the artifact, the POM, and all attached artifacts --> <plugin> <groupId>org.apache.maven.plugins</groupId> <artifactId>maven-gpg-plugin</artifactId> <inherited>true</inherited> <configuration> <passphrase>${gpg.passphrase}</passphrase> </configuration> <executions> <execution> <goals> <goal>sign</goal> </goals> </execution> </executions> </plugin> <!-- We want to deploy the artifact to a staging location for perusal --> <plugin> <groupId>org.apache.maven.plugins</groupId> <artifactId>maven-deploy-plugin</artifactId> <inherited>true</inherited> <configuration> <altDeploymentRepository>${deploy.altRepository}</altDeploymentRepository> <updateReleaseInfo>true</updateReleaseInfo> </configuration> </plugin> </plugins> </build> </profile>

7. Build the new branches tree as you normally would to ensure that it is correct.
8. Stage the release for a vote.
   When you are ready to create a release candidate, build the new branches tree that will soon be released using the following command.

   No Format
   mvn -Prelease,default deploy

9. Export and tar/zip the source to be voted on for the release using the following commands:

   No Format
   svn export https://svn.apache.org/repos/asf/geronimo/server/branches/2.1.1 geronimo-2.1.1-src tar -zcvf geronimo-2.1.1-src.tar.gz geronimo-2.1.1-src

10. Copy the tar ball to a publicly accessible location. Put it for a vote along with the staging release you created earlier. In the vote notice, please include the precise names and versions being voted on (e.g. geronimo-javamail_1.4_spec-1.1) and the svn urls to the current source and where the tag will be created.
11. Copy from the staging repo to the production repo.
    Once the release is deemed fit for public consumption it can be transfered to a production repository where it will be available to all users. Note: Current version of the stage plugin is 1.0-alpha-1.
    Here is an example on how to use the stage plugin:

    No Format
    mvn stage:copy -Dsource="http://people.apache.org/<your apache id>/staging-repo/<siteId>" \ -Dtarget="scp://people.apache.org/www/people.apache.org/repo/m2-ibiblio-rsync-repository" \ -Dversion=2.3 \ -DtargetRepositoryId=apache.releases

    Note
    The version parameter is currently ignored but specify the correct version anyway. The entire staging repository is synced, not just the given version or the current project.

    Info
    Ensure that the files you copy to the rsync directory have 0775 dir permission and a 0664 file permission set on them.

12. Move the branches to tags using the following command.

    No Format
    svn mv SRC-URL DEST-URL -m "Reason for this commit".

Notice

The original process in this document was voted on by the Geronimo community. Please formally propose all changes to dev@geronimo.apache.org.

...