Releasing Titan
===============

Prerequisites
-------------

The release process has only been tested on Linux.  The following
tools must be installed.

* [expect](http://expect.sourceforge.net/)
* [gollum-site](https://github.com/dreverri/gollum-site)
* [gpg](http://www.gnupg.org/)

~/.m2/settings.xml will need the following entries.

```xml
<settings>
  <servers>
    <server>
      <id>sonatype-nexus-snapshots</id>
      <username>...</username>
      <password>...</password>
    </server>
    <server>
      <id>sonatype-nexus-staging</id>
      <username>...</username>
      <password>...</password>
    </server>
    <server>
      <id>aurelius.s3</id>
      <username>AWS Key ID</username>
      <password>AWS Secret Key</password>
    </server>
  </servers>
</settings>
```

Release Steps
-------------

### Preparing Documentation

Update version-sensitive wiki pages and doc/HTML files in the repo.

Wiki pages:

* Home
* Release-Notes
* Version-Compatibility
* Upgrade-Instructions
* Acknowledgements
* Downloads

Files in the main repo:

* CHANGELOG.textile
* NOTICE.txt
* UPGRADE.textile
* titan-site/src/site-resources/index.html
  (this template generates a new http://thinkaurelius.github.io/titan/)

Some of these updates could potentially be automated, but tweaking
documentation before a release will always require at least human in
the loop.

### Preparing the Local Repository

Commit or stash any uncommitted changes.

Recommended but not required:

* Push any unpushed commits on master with <code>git push origin
  master</code>
* Delete untracked files and directories in the clone by running
  <code>git clean -fd</code>

### Deploying Artifacts & Archives

```bash
# This does not push anything.  It creates two local commits and a tag.
# You will be prompted for the release version and the next dev version.
mvn release:prepare -Prelease-plugin-hack

# The tag name generated by release:prepare does not match the general
# pattern established before we started using the release plugin.  This
# script deletes the tag and creates it with a pattern-conformant name.
titan-dist/target/util-scripts/rewrite-tag.sh release.properties

# Proceeding beyond this comment commits you to either complete the
# rest of the release steps or, if you must abort, to cleanup
# afterward.  The next command is world-visible in that it deploys
# jars to Sonatype OSS staging and uploads .zip/.tar.bz2 archives to
# S3.  It's not a huge deal -- the Sonatype staging artifacts won't
# show up on Maven Central without additional steps and there will be
# no links pointing people to the artifacts in S3 -- but it's still
# technically world-visible.  In contrast, commands above this comment
# were limited to local effects invisible to the wider Internet.
mvn clean javadoc:jar verify deploy -Paurelius-release
# You can append -DskipTests=true above if you've already run the tests
```

### Checking Artifacts & Archives

This is a good time to inspect the archives just uploaded to
http://s3.thinkaurelius.com/downloads/titan/.  Directory listing is
normally disabled on that directory, so you may need to login to the
S3 console to list the contents and check that nothing's out of place.

If S3 looks good, then inspect and close the staging repository that
the deploy phase automatically created on https://oss.sonatype.org/.

If you decide to abort at this stage, then:

* Delete any artifacts just uploaded to S3
* Drop the staging repository in Sonatype OSS
* Run the following commands to delete your local git changes

```bash
#
#                        WARNING
#
# This will obliterate all local commits and uncommitted files.
# Only copy and paste this code segment if you want to abort a
# partially-completed release.  Replace $RELEASE_VERSION by the
# version just attempted.
git reset --hard origin/master
git tag -d $RELEASE_VERSION
git clean -fd
```

Assuming everything looked fine on OSS Sonatype and S3, we'll move on
to updating gh-pages locally.

### Generating new Javadoc & Wikidoc for gh-pages

```bash

# This clones the repo to titan-site/target/pages.  It checks out the
# gh-pages branch, then populates wikidoc/$RELEASE_VERSION/ and
# javadoc/$RELEASE_VERSION/ with a copy of the wiki exported using
# gollum-site and a copy of the current javadoc (respectively).  It
# also replaces the wikidoc/current/ and javadoc/current/ directories
# with copies of files for $RELEASE_VERSION.  Finally, it generates a
# new index.html.
#
# It commits none of this.  The script will prompt you to check its
# work and remind you to commit as it exits.
titan-site/target/site-scripts/gh-pages-update.sh release.properties
# Check output in titan-site/target/pages...
cd titan-site/target/pages
git diff --cached index.html
git status
# Commit gh-pages updates and return to the repo root
git commit
cd -
```

### Release to Maven Central and Push to Github

Release the Sonatype OSS repository that you inspected and closed
earlier.  It will appear on Maven Central in an hour or two.

Finally, push your local changes to Github:

```bash 
# Replace $RELEASE_VERSION by the actual version
git push origin master
git push origin refs/tags/$RELEASE_VERSION
cd titan-site/target/pages
git push origin gh-pages
```

### Deploy a New Snapshot

To kickoff the next round of development, deploy a copy of the new
SNAPSHOT version's artifacts to the Sonatype OSS snapshots repository.

```bash
# From the repository root
git checkout master
mvn clean deploy
```