upgrade thoughts

long comments :)

Upgrade.hs

@@ -38,12 +38,52 @@ upgrade = do
 
 upgradeFrom1 :: Annex Bool
 upgradeFrom1 = do
-	showSideAction "Upgrading object directory layout..."
+	showSideAction "Upgrading object directory layout v1 to v2..."
 	error "upgradeFrom1 TODO FIXME"
 
+	-- v2 adds hashing of filenames of content and location log files.
+	-- 
+	-- Key information is encoded in filenames differently.
+	-- 
+	-- When upgrading a v1 key to v2, file size metadata needs to be
+	-- added to the key (unless it is a WORM key, which encoded
+	-- mtime:size in v1). This can only be done when the file content
+	-- is present. 
+	--
+	-- So there are two approaches -- either upgrade
+	-- everything, leaving out file size information for files not
+	-- present in the current repo; or upgrade peicemeil, only
+	-- upgrading keys whose content is present.
+	--
+	-- The latter approach would mean that, until every clone of an
+	-- annex is upgraded, git annex would refuse to operate on annexed
+	-- files that had not yet been committed. Unless it were taught to
+	-- work with both v1 and v2 keys in the same repo.
+	--
+	-- Another problem with the latter approach might involve content
+	-- being moved between repos while the conversion is still
+	-- incomplete. If repo A has already upgraded, and B has not, and B
+	-- has K, moving K from B -> A would result in it lurking
+	-- unconverted on A. Unless A upgraded it in passing. But that's
+	-- getting really complex, and would mean a constant trickle of
+	-- upgrade commits, which users would find annoying.
+	--
+	-- So, the former option it is! Note that file size metadata
+	-- will only be used for detecting situations where git-annex
+	-- would run out of disk space, so if some keys don't have it,
+	-- the impact is small. At least initially. It could be used in the
+	-- future by smart auto-repo balancing code, etc.
+	--
+	-- Anyway, since v2 plans ahead for other metadata being included
+	-- in keys, there should probably be a way to update a key.
+	-- Something similar to the migrate subcommand could be used,
+	-- and users could then run that at their leisure. Or, this upgrade
+	-- could to that key update for all keys that have been converted
+	-- and have content in the repo.
+
 upgradeFrom0 :: Annex Bool
 upgradeFrom0 = do
-	showSideAction "Upgrading object directory layout..."
+	showSideAction "Upgrading object directory layout v0 to v1..."
 	g <- Annex.gitRepo
 
 	-- do the reorganisation of the files
@@ -56,6 +96,9 @@ upgradeFrom0 = do
 	fixlinks files
 	Annex.queueRun
 
+	-- Few people had v0 repos, so go the long way around from 0 -> 1 -> 2
+	upgradeFrom1
+
 	setVersion
 
 	return True

debian/changelog

@@ -1,5 +1,6 @@
 git-annex (0.24) UNRELEASED; urgency=low
 
+  * TODO: upgrade v1 -> v2
   * Reorganized annexed object store. annex.version=2
   * Colons are now avoided in filenames, so bare clones of git repos
     can be put on USB thumb drives formatted with vFAT or similar