MusicBrainz-Ruby 0.3.0 Release Notes
====================================

Overview
========
1. API Changes
2. Signed RubyGems Package
3. URLs

1. API Changes
==============
There are a couple of minor changes to the MusicBrainz 0.3.0 API which
may be incompatible with code written for earlier versions of
MusicBrainz-Ruby.  The changes are:
    
  * Exceptions are now properly wrapped in a MusicBrainz::Error class.
  * All of the new query types are conditional, depending on the version
    of MusicBrainz installed.  This was done to maintain compatability 
    with older versions of the MusicBrainz library.  A full list of the
    new conditional query types is available in the ChangeLog (linked
    above).
  * MusicBrainz::TRM#finalize returns true for success, instead of
    false.
    
The first two changes can be worked around by using a bit of Ruby-fu to
test for the availability of particular constant.  The code to check for
the presence of MusicBrainz::Error, for example, would look something
like this:

  if MusicBrainz.const_defined('Error')
    # client library has new MusicBrainz::Error class,
    # use new behavior
  else
    # client library doesn't have new error handling, 
    # fall back to old behavior
  end
    
A similar bit of Ruby-fu can be used to test for query constants:

  if MusicBrainz::Query.const_defined?('AlbumGetAmazonAsin')
    # have given query constant, do whatever
  else
    # don't have constant, do other stuff
  end

Finally, if all else fails, you can test for specific versions of
MusicBrainz-Ruby by checking the value of MusicBrainz::VERSION.

2. Signed RubyGems Package
==========================
The gem file for MusicBrainz-Ruby 0.3.0 is cryptographically signed
using the (relatively) new RubyGems signing interface.  Full
documentation for both deploying and using the RubyGems certificate
interface is available online in the RubyGems manual, but here's a brief
overview of the steps necessary to validate and verify a signed gem.

By the way, if you skipped ahead and gawked at the instructions below,
remember that none of this is _required_ to use a signed gem; they can
be installed and run exactly like any other gem file.  That said,
verifying the authenticity of package files is a good way to save
yourself the headache of a future security fiasco.  So, without any
further ado...

First, you'll need to download and verify the certificates used to sign
the gem file itself.  Here are the URLs:

  http://pablotron.org/files/certs/ca.crt
  http://pablotron.org/files/certs/ca.crt.asc
  http://pablotron.org/files/certs/rubygems.crt
  http://pablotron.org/files/certs/rubygems.crt.asc

The .crt files are PEM-encoded X.509 certificate files, and the .asc
files are OpenPGP signatures of their certificate counterparts.

If you have GnuPG installed, you can verify the signatures on each of
these files like so:

  # grab my PGP key from your local PGP keyserver
  # (also available online at http://pablotron.org/files/pabskey.asc)
  gpg --recv-keys 82C29562 wwwkeys.us.pgp.net

  # alternatively, you can grab it online like so:
  # wget -O- http://pablotron.org/files/pabskey.asc | gpg --import


  # verify that both certificates were signed by me
  for pgp_sig in {ca,rubygems}.crt.asc; do pgp_sig $sig; done

If everything checks out okay and you either, a) believe that my
PGP signature is legitimate, or b) can establish a trusted relationship
via GnuPG, then it's reasonably safe to assume that the certificates
were, in fact, issued by me.  And I'm a trustworthy guy, so let's add my
certificates to RubyGems's list of trusted certificates:

  # add both certificates to your list of trusted gem certs
  for cert in {ca,rubygems}.crt; do sudo gem cert -a $cert; done

(If you change your mind and decide either me or my certs aren't
trustworthy, you can use "gem cert -r" to remove the certificates from
your trust list).

At this point we're ready to install the gem.  It's business as usual,
except for an additional flag to set our RubyGems security policy.
The HighSecurity policy tells RubyGems to only install signed gem files
that are from trusted sources.  Here's how we enable it:

  # URL to gem file.  once it's in the RubyGems repositories, you can
  # change this from a URL to just the package nama 'mb-ruby'.
  gem_url=http://pablotron.org/files/gems/mb-ruby-0.3.0.gem

  # install gem from remote url using the high security policy
  sudo gem install $gem_url -P HighSecurity

And we're done!  If the gem file isn't signed, there was a problem with
the validity of the certificates or the gem file, gem will refuse to
install the gem file.  The best part is, that is the _only_ step you
have to perform on any gem signed by me in the future.

3. URLs
=======
* Tarball (tar.gz):
  * Download:   http://pablotron.org/files/mb-ruby-0.3.0.tar.gz
  * Signature:  http://pablotron.org/files/mb-ruby-0.3.0.tar.gz.asc
* RubyGems Package (gem):
  * Download:   http://pablotron.org/files/mb-ruby-0.3.0.tar.gz
  * Signature:  http://pablotron.org/files/mb-ruby-0.3.0.tar.gz.asc
* Documentation:
  * ChangeLog:  http://pablotron.org/software/mb-ruby/ChangeLog-0.3.0
  * API Docs:   http://pablotron.org/software/mb-ruby/doc/
  * Release Notes: http://pablotron.org/software/mb-ruby/release_notes-0.3.0.txt