From cc0e9112b4154b7612539a321888bd9a2f38839a Mon Sep 17 00:00:00 2001
From: Adrian Sampson <adrian@radbox.org>
Date: Thu, 24 Jan 2013 16:55:00 -0800
Subject: [PATCH] document migration from 1.0 to 1.1

---
 docs/guides/index.rst     |  1 +
 docs/guides/migration.rst | 52 +++++++++++++++++++++++++++++++++++++++
 docs/reference/config.rst |  2 +-
 3 files changed, 54 insertions(+), 1 deletion(-)
 create mode 100644 docs/guides/migration.rst

diff --git a/docs/guides/index.rst b/docs/guides/index.rst
index 0544e2b55..d9ec06d9b 100644
--- a/docs/guides/index.rst
+++ b/docs/guides/index.rst
@@ -10,3 +10,4 @@ guide.
 
    main
    tagger
+   migration
diff --git a/docs/guides/migration.rst b/docs/guides/migration.rst
new file mode 100644
index 000000000..c00296e58
--- /dev/null
+++ b/docs/guides/migration.rst
@@ -0,0 +1,52 @@
+Upgrading from 1.0
+==================
+
+Prior to version 1.1, beets used a completely different system for
+configuration. The config file was in "INI" syntax instead of `YAML`_ and the
+various files used by beets were (messily) stored in ``$HOME`` instead of a
+centralized beets directory. If you're upgrading from version 1.0 or earlier,
+your configuration syntax (and paths) need to be updated to work with the
+latest version.
+
+Fortunately, this should require very little effort on your part. When you
+first run beets 1.1, it will look for an old-style ``.beetsconfig`` to
+migrate. If it finds one (and there is no new-style
+``config.yaml`` yet), beets will warn you and then
+transparently convert one to the other. At this point, you'll likely want to:
+
+* Look at your new configuration file (find out where in
+  :doc:`/reference/config`) to make sure everything was migrated correctly.
+* Remove your old configuration file (``~/.beetsconfig`` on Unix;
+  ``%APPDATA%\beetsconfig.ini`` on Windows) to avoid confusion in the future.
+
+You might be interested in the :doc:`/changelog` to see which configuration
+option names have changed.
+
+What's Migrated
+---------------
+
+Automatic migration is most important for the configuration file, since its
+syntax is completely different, but two other files are also moved. This is to
+consolidate everything beets needs in a single directory instead of leaving it
+messily strewn about in your home directory.
+
+First, the library database file was at ``~/.beetsmusic.blb`` on Unix and
+``%APPDATA%\beetsmusic.blb`` on Windows. This file will be copied to
+``library.db`` in the same directory as your new configuration file. Finally,
+the runtime state file, which keeps track of interrupted and incremental
+imports, was previously known as ``~/.beetsstate``; it is copied to a file
+called ``state.pickle``.
+
+Feel free to remove the old files once they've been copied to their new homes.
+
+Manual Migration
+----------------
+
+If you find you need to re-run the migration process, just type ``beet
+migrate`` in your shell. This will migrate the configuration file, the
+database, and the runtime state file all over again. Unlike automatic
+migration, no step is suppressed if the file already exists. If you already
+have a ``config.yaml``, for example, it will be renamed to make room for the
+newly migrated configuration.
+
+.. _YAML: http://en.wikipedia.org/wiki/YAML
diff --git a/docs/reference/config.rst b/docs/reference/config.rst
index 7ede9f96b..73bca4001 100644
--- a/docs/reference/config.rst
+++ b/docs/reference/config.rst
@@ -37,7 +37,7 @@ library
 ~~~~~~~
 
 Path to the beets library file. By default, beets will use a file called
-``beetsmusic.blb`` alongside your configuration file.
+``library.db`` alongside your configuration file.
 
 directory
 ~~~~~~~~~