Introduction

This process describes what needs to be done in order to release the MyFaces Portlet Bridge. The release process for the MyFaces portlet Bridge is based of Maven and follows the Apache release process. The intention of this document is to allow a MyFaces committer to release the portal project.

Getting Started

There are a number of things you need to do before beginning the release process. If you've release other MyFaces products before, chances are you can skip this section.

External Tools

The following tools will be needed in order to perform the release process:

Initial Setup

  1. Registering your GnuPG key
    • All Apache release artifacts must be signed using GnuPG. This is to ensure the authenticity of the released artifacts. Once you have generated a key for your Apache

      email address (or added an Apache Email Address to your existing key), then you also need to register the public portion of your key with the Apache MyFaces "Web of Trust" as well as a public key server. In short, this means:

      • Adding your public key to the KEYS file which you will find at /x1/www/www.apache.org/dist/myfaces on the people.apache.org host.

      • Adding your public key to a public keystore like http://pgp.mit.edu/.

  2. Server settings
    • For the deploy plugin to being able to upload the artifacts you must add the right settings for the "myfaces-staging" server. You may either use your username and password or provide your private key file.
      <settings xmlns="http://maven.apache.org/POM/4.0.0"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 
                            http://maven.apache.org/xsd/settings-1.0.0.xsd">
        ...
        <servers>
          <server>
            <id>myfaces-staging</id>
            <username>....</username>
            <privateKey>C:\....\myapachekey.ppk</privateKey>
            <filePermissions>664</filePermissions>
            <directoryPermissions>775</directoryPermissions>
            <configuration>
              <sshExecutable>C:\....\putty-0.60\plink</sshExecutable>
              <scpExecutable>C:\....\putty-0.60\pscp</scpExecutable>
            </configuration>
          </server>
        </servers>
        ...
      </settings>
    • See maven-deploy-plugin ssh examples for more info.

      Important: Make sure you access the "people.apache.org" host manually at least once before running the release plugin by doing a ssh people.apache.org (*nix users) or plink.exe people.apache.org (Windows putty users) on the command line. You will be asked to accept the server certificate. You have to answer "permanently" for the Maven upload to function properly later.

  3. Preparing your people.apache.org home
    • In order to have some temporary webspace available on people.apache.org, you need to log into the server via ssh and in your home directory create a public_html directory and put an index.html file in it. This can be blank. This will give you a webspace rooted at http://people.apache.org/~<username> where you can store your temporary artifacts.

Release Process

The release process consists of three phases. The first phase, preparing the release, takes place first and involves creating a tag for the released project and creating the build artifacts for review. The second phase is the voting phase which involves sending out an email to the developer list and getting approval from the community to release the project. The last phase, performing the release, involves updating the various Apache websites, making the artifacts available online, and sending out a release announcement. Each of these phases are documented, in detail, in the sections below.

Please Note: The MyFaces Portlet bridge has had a number of alpha release phases and it's expected to have a number of beta release phases as well. The release process for alpha and beta releases differs slightly from a standard release cycle. If you are generating an Alpha or Beta release of a project, please see the section "Alpha/Beta Release Process" below.

Preparing the Release

  1. Open up a command window and cd to the directory you want to use to store the release
  2. Check out a new trunk by typing: svn checkout https://svn.apache.org/repos/asf/myfaces/portlet-bridge/core/trunk release_trunk. If you are trying to release the portlet-bridge 2.0.x branch, use https://svn.apache.org/repos/asf/myfaces/portlet-bridge/core/trunk_2.0.x instead.

  3. Type: cd release_trunk

  4. Type: mvn -DprepareRelease=true}} release:prepare This should begin to ask you several questions about what version number you'd like to release as and what version number you would like trunk to become. Generally accepting the defaults here is best. This will generate a new tag for your source code and will try to perform a checkin.

  5. Go back to the directory which contains your release_trunk directory and check out the new tag. Type: svn checkout https://svn.apache.org/repos/asf/myfaces/portlet-bridge/core/tags/portlet-bridge-<tag version number> portlet-bridge-<tag version number>

  6. Create a new staging directory that will hold all your artifacts
  7. Type: cd portlet-bridge-<tag version number>

  8. Type: mvn clean source:jar install deploy -DaltDeploymentRepository=sobryan::default::file:<staging directory> -DperformRelease=true. This will prompt you for your gpg passphrase during the build if you have one. Additionally you can add -Dgpg.passphrase=<passphrase> to the command line to avoid being prompted. This will create the repository artifacts in your staging directory.

  9. Type: cd assembly

  10. Type: mvn clean install package assembly:assembly. This will prompt you for your gpg passphrase during the build if you have one. Additionally you can add -Dgpg.passphrase=<passphrase> to the command line to avoid being prompted. This will create the repository artifacts in your staging directory. This will store the binary packages in your target/assembly/out directory.

  11. Type: cd target/assembly/out

  12. For each file in this directory, you will need to sign the packages. If using *nix bash, this can be done simply by typing: for path in `ls -b`;do echo <passphrase>|gpg --clearsign --passphrase-fd "$path" -o "$path.asc";done. On Windows if you have the GPGee module installed for GPG4win, you can simply highlight the files and use right-click menu to sign them. If using GPGee, create a detached key, with no encryption, and be sure to check the "Text output (ASCII Armor)" setting. In either case, this will generate a bunch of .asc files.

  13. Now we need to checksum all the files in this directory (including the .asc files). MyFaces expects two type of checksums to be generated, md5 checksum and sha1. You need to generate both of these checksums for each file and put the content in test files with the .md5 and .sha1 extensions respectively. If you use linux you can generate these from bash by typing the following: for path in `ls -b *.zip *.tar.gz *.asc`;do md5sum $path > $path.md5;sha1sum $path > $path.sha1;done

  14. Copy the files from the target/assembly/out directory to the root of your staging directory. Be sure to take the checksums and signature files as well.
  15. Go into your tags /examples directory and type mvn clean source:jar install This will build the examples.

  16. Repeat steps 9 - 14 for the assembly directory under examples.
  17. Move all of the files in your staging directory to a subdirectory under your home on people.apache.org. I generally tar everything up, send it over, and then untar it. Make sure the contents of the staging directory is put somewhere under your public_html folder. I put my release artifacts under public_html/portlet-bridge/portlet-bridge-<tag version number>. If you put it in a different location, you may need to modify the sample letter below.

Whew! It was painful, but you did it. I created a python script which essentially does steps 8 - 17 for me and trust me when I say it really speeds things up.

Voting on the Release

As a rule of thumb, the vote should remain open for 72 hours and have at least 3 +1 votes. Although there is no "veto" of a release, it is often good form to address any -1 votes. Ultimately, though, when the vote is close is up to the release manager which is, basically, you. We've had release votes that have been open for two weeks because we were awaiting word back on a copyright issue. To start a vote, send an email to the dev@myfaces.apache.org mailing list. Be sure to include [VOTE] in the subject. Here is a standard form email you can use for the Portlet Bridge, just replace the appropriate text:

Performing the Release

TODO

Alpha/Beta Release Process

TODO

Releasing_the_MyFaces_Portlet_Bridge (last edited 2009-09-20 23:01:33 by localhost)