Release Process


The following is a step-by-step procedure for releasing a new version of Google-Gson.
  1. Go through all open bugs and identify which will be fixed in this release. Mark all others with an appropriate release tag. Identify duplicates, and close the bugs that will never be fixed. Fix all bugs for the release, and mark them fixed.
  2. Edit pom.xml and update the versions listed for Export-Package to the target version. Also add any new Java packages that have been introduced in Gson.
  3. Ensure all changelists are code-reviewed and have +1
  4. Ensure that your ~/.m2/settings.xml is configured properly (see steps below)
  5. cd gson. Ensure there are no open files and all changes are committed. 
  6. Run mvn release:clean
  7. Do a dry run: mvn release:prepare -DdryRun=true
  8. Start the release: mvn -Dusername=<your-google-username> -Dpassword=<your-google-code-password> release:prepare
    1. Answer questions: usually the defaults are fine. 
    2. This will do a full build, change version from -SNAPSHOT to the released version, commit and create the tags. It will then change the version to -SNAPSHOT for the next release.
    3. To release a specific version, use: mvn release:perform -DconnectionUrl=scm:svn:
  9. Ensure you have defined sonatype-nexus-staging in your maven settings.xml and run mvn -s /home/<username>/.m2/settings.xml -Dusername=<your-google-username> -Dpassword=<your-google-code-password> release:perform
  10. Log in to Nexus repository manager at Sonatype and close the staging repository for Gson. If you run into an error regarding missing signatures, you need to manually upload the artifacts using mvn gpg:sign-and-deploy-file for Gson binary, source and javadoc jars.
    • cp -r ~/.m2/repository/com/google/code/gson/gson/1.7.2  /tmp; cd /tmp/1.7.2
    • mvn gpg:sign-and-deploy-file -Durl= -DrepositoryId=sonatype-nexus-staging -DpomFile=gson-1.7.2.pom -Dfile=gson-1.7.2-javadoc.jar -Dclassifier=javadoc
    • mvn gpg:sign-and-deploy-file -Durl= -DrepositoryId=sonatype-nexus-staging -DpomFile=gson-1.7.2.pom -Dfile=gson-1.7.2-sources.jar -Dclassifier=sources
    • mvn gpg:sign-and-deploy-file -Durl= -DrepositoryId=sonatype-nexus-staging -DpomFile=gson-1.7.2.pom -Dfile=gson-1.7.2.jar
  11. Close the Gson repository. Download and sanity check all downloads. Do not skip this step! Once you release the staging repository, there is no going back. It will get synced with maven central and you will not be able to update or delete anything. Your only recourse will be to release a new version of Gson and hope that no one uses the old one.
  12. Release the staging repository for Gson. Gson will now get synced to Maven central with-in the next hour. For issues consult Sonatype Guide.
We also need to do a version of the following commands: After locally changing the version in pom.xml to the released version.
  1. Perform the following Maven commands, in order:
    • mvn clean
    • mvn package source:jar javadoc:jar assembly:assembly
  2. Navigate to target/dist and perform a sanity check on the zip bundle:
    • unzip zip file
    • jar tvf on the jar files and verify the proper files are in the jars
  3. Upload the zip bundle to the GSON downloads page (label this upload as "Featured")
  4. Deprecate old Gson version (click on version label and set the "Featured" label to "Deprecated")
  5. Create a jar for the stream classes:
    • jar cvfM target/google-gson-stream-1.6.jar -C target/classes/ com/google/gson/stream/
  6. Test the stream jar using vogar.
    • vogar --mode jvm --classpath target/google-gson-stream-1.6.jar src/test/java/com/google/gson/stream/*
  7. Upload the stream jar to the GSON downloads page without any label
  8. Copy generated JavaDocs from target/apidocs to trunk/gson/docs/javadocs
    • cp -r target/apidocs/* docs/javadocs
  9. Configure your SVN client to automatically assign MIME types for Javadocs. Instructions from Eric Burke's Blog.
    • Or if you are not satisfied with the above solution like can always do the following:
      • find docs -name "*.html" | xargs svn propset svn:mime-type text/html
      • find docs -name "*.gif" | xargs svn propset svn:mime-type image/gif
  10. Commit the JavaDoc changes into the repository
  11. Update the version in the Using Gson with Maven2 page
  12. Update Gson Roadmap to move the release down under the "Released section". Also, look at all bugs that were fixed and add a few lines describing what changed in the release.
  13. Create a post on the Gson Discussion Forum
  14. Update the release version in Wikipedia and update the current "stable" release.

Configuring a machine for deployment to Sonatype Repository

(Borrowed heavily from Doclava release process)
  1. Install/Configure GPG following this guide
  2. Create encrypted passwords
  3. Create ~/.m2/settings.xml similar to as described in Doclava release process
  4. Now for deploying a snapshot repository, use mvn deploy

Getting Maven Publishing Privileges

1. Signup for a Sonatype account following instructions under 2) at

2. Ask one of the existing members of the repository to create a JIRA ticket (Step 3 of above document) to add you to the publisher list.

Diffing Releases with jdiff

Download jdiff from sourceforge.

Download the previous release from the GSON downloads page. unzip it. cd to the google-gson-xxx directory and run jar xvf gson-xxx-sources.jar

Create a build.xml file to execute jdiff from ant. Set the paths to jdiff home, version numbers, and the paths to the old and new versions of GSON:

<?xml version="1.0" encoding="UTF-8"?>
<project name="jdiff" default="jdiff_report" basedir=".">
<target name="jdiff_report" depends="">
  <property name="JDIFF_HOME" value="/home/jessewilson/Projects/jdiff-1.1.1" />
  <taskdef name="jdiff" 
           classpath="${JDIFF_HOME}/antjdiff.jar" />
  <mkdir dir="target/myreport"/>
  <jdiff destdir="target/myreport" verbose="on" stats="on" docchanges="on">
    <old name="Version 1.5">
      <!-- This is the location of your old source files -->
      <dirset dir="/home/jessewilson/Projects/google-gson-1.5/source" includes="com/**" />
    <new name="Version 1.6">
      <dirset dir="/home/jessewilson/Projects/google-gson/gson/src/main/java" includes="com/**" />

Run ant.

Running Benchmarks or Tests on Android

Download vogar
Put adb on your $PATH and run:
vogar --benchmark --classpath gson.jar path/to/

For example, here is how to run the CollectionsDeserializationBenchmark:

export ANDROID_HOME=~/apps/android-sdk-mac_x86
export PATH=$PATH:$ANDROID_HOME/platform-tools/:$ANDROID_HOME/android-sdk-mac_x86/tools/
$VOGAR_HOME/bin/vogar  --benchmark --sourcepath ../gson/src/main/java/  src/main/java/com/google/gson/metrics/ -- --vm "app_process -Xgc:noconcurrent,app_process"