[DRE-commits] [sup-mail] 01/01: Include migration page from Sup wiki

[Per Andersson]

This is an automated email from the git hooks/post-receive script.

avtobiff pushed a commit to branch master
in repository sup-mail.

commit 605bb182284e181f3a1dbf2b0e9005237f6d5bfc
Author: Per Andersson <avtobiff at gmail.com>
Date:   Thu Sep 4 00:39:02 2014 +0200

    Include migration page from Sup wiki
---
 debian/Migration-0.13-to-0.14.md | 47 ++++++++++++++++++++++++++++++++++++++++
 debian/NEWS                      |  2 +-
 debian/changelog                 |  1 +
 debian/sup-mail.docs             |  1 +
 4 files changed, 50 insertions(+), 1 deletion(-)

diff --git a/debian/Migration-0.13-to-0.14.md b/debian/Migration-0.13-to-0.14.md
new file mode 100644
index 0000000..ad0072c
--- /dev/null
+++ b/debian/Migration-0.13-to-0.14.md
@@ -0,0 +1,47 @@
+With the sup release 0.14 some major changes require some migration (and
+cautionary steps).
+
+
+## First steps
+
+Prior to updating sup, please back up your index, and preferably the whole
+.sup directory. 
+
+1. Use [sup-dump](https://github.com/sup-heliotrope/sup/wiki/Backing-up-the-index)
+   to back up the index.
+2. Back up your ~/.sup directory (with config files and index)
+
+
+## Migration
+
+Before 0.14, Sup used syck to store YAML documents (the format of Sup's
+configuration files). In version 0.14 and later, Sup uses the Psych format
+instead. When upgrading, please use the migration utility.
+
+
+### Ruby 2.0 and earlier
+
+After upgrading, run ```sup-psych-ify-config-files``` to update the format of
+the ```.sup/sources.yaml``` file. If something goes wrong, you probably need
+to manually re-add the sources (make sure that the source IDs match the old
+configuration!).
+
+
+### Ruby 2.1 or later
+
+Because later versions of Ruby drop support for the old syck format
+completely, the migration script will not run with Ruby >= 2.1
+([#268](https://github.com/sup-heliotrope/sup/pull/268)), and will eventually
+be completely removed. There are several possible options:
+
+* Don't make any changes to the configuration files and hope for the best
+  (this is likely to work, but be sure to back up everything first!)
+* Downgrade to Ruby <= 2.0 and use the migration script
+* Re-add syck support with the [syck gem](http://rubygems.org/gems/syck)
+  (experienced developers only)
+* Run ```sup-config``` to re-add your source(s). You must then manually edit
+  ```.sup/sources.yaml``` and edit the Source IDs (```id```) to match the old
+  configuration.
+* Make some changes manually. Some tips are available
+  [here](http://devblog.arnebrasseur.net/2014-02-yaml-syck-vs-psych) and
+  [here](http://docs.solanolabs.com/HandlingFailures/KnownIssues/psych-vs-syck-yaml-parsing/).
diff --git a/debian/NEWS b/debian/NEWS
index ec4fc4c..01e19d2 100644
--- a/debian/NEWS
+++ b/debian/NEWS
@@ -8,7 +8,7 @@ sup-mail (0.19.0-1) unstable; urgency=medium
   If you are updating from Sup <= 0.13 (wheezy version is 0.12.1), you may
   need to migrate your .sup/sources.yaml file. See
   https://github.com/sup-heliotrope/sup/wiki/Migration-0.13-to-0.14 for more
-  details.
+  details. The wiki page is also installed locally in /usr/share/doc/sup-mail.
 
  -- Caitlin Matos <caitlin.matos at zoho.com>  Tue, 26 Aug 2014 12:19:34 -0400
 
diff --git a/debian/changelog b/debian/changelog
index 9702abf..c2c6b87 100644
--- a/debian/changelog
+++ b/debian/changelog
@@ -30,6 +30,7 @@ sup-mail (0.19.0-1) unstable; urgency=medium
   * d/rules: Remove bin/sup-sync-back removal, not included upstream
   * Bump Standards-Version to 3.9.5, no changes needed
   * Add man pages for sup-psych-ify-config-files and sup-sync-back-maildir
+  * Include migration page from Sup wiki
 
  -- Caitlin Matos <caitlin.matos at zoho.com>  Tue, 26 Aug 2014 14:04:01 -0400
 
diff --git a/debian/sup-mail.docs b/debian/sup-mail.docs
index 50ce191..57eccc6 100644
--- a/debian/sup-mail.docs
+++ b/debian/sup-mail.docs
@@ -1,3 +1,4 @@
 doc/*
 README.md
 ReleaseNotes
+debian/Migration-0.13-to-0.14.md

-- 
Alioth's /usr/local/bin/git-commit-notice on /srv/git.debian.org/git/pkg-ruby-extras/sup-mail.git