===========================
Sumatra 0.5.0 release notes
===========================

*February 18th 2013*

Welcome to Sumatra 0.5.0!

Overview
--------

Sumatra 0.5 development has mostly been devoted to polishing. There were a bunch
of small improvements, with contributions from several new contributors. The
Bitbucket_ pull request workflow seemed to work well for this. The main changes
are:

* working directory now captured (as a parameter of :class:`LaunchMode`);
* data differences are now based on content, not name, i.e. henceforth two files
  with identical content but different names (e.g. because the name contains a
  timestamp) will evaluate as being the same;
* improved error messages when a required version control wrapper is not
  installed;
* dependencies now capture the source from which the version was obtained
  (e.g. repository url);
* YAML-format parameter files are now supported (thanks to Tristan Webb);
* added "upstream" attribute to the :class:`Repository` class, which may contain
  the URL of the repository from which your local repository was cloned;
* added :class:`MirroredFileSystemDataStore`, which supports the case where files
  exist both on the local filesystem and on some web server (e.g. DropBox);
* the name/e-mail of the user who launched the computation is now captured
  (first trying :file:`~/.smtrc`, then the version control system);
* there is now a choice of methods for auto-generating labels when they are not
  supplied by the user: timestamp-based (the default and previously the only
  option) and uuid-based. Use the "-g" option to :command:`smt configure`;
* you can also specify the timestamp format to use (thanks to Yoav Ram);
* improved API reference documentation.


Interfaces to documentation systems
-----------------------------------

The one big addition to Sumatra is a set of tools to include figures and other
results generated by Sumatra-tracked computations in documents, with links to
full provenance information: i.e. the full details of the code, input data and
computational environment used to generate the figure/result.

The following tools are available:

* for reStructuredText/Sphinx: an "smtlink" role and "smtimage" directive.

* for LaTeX, a "sumatra" package, which provides the "\\smtincludegraphics" command.

see :doc:`../publishing` for more details.


Bug fixes
---------

A `handful of bugs`_ have been fixed.

.. _`handful of bugs`: https://neuralensemble.org/trac/sumatra/query?status=closed&group=resolution&milestone=0.5
.. _Bitbucket: https://bitbucket.org/apdavison/sumatra