v1.0 Release Notes
==================

INTRODUCTION

Verseek, short for Version Seeker, is an abstract interface for
transparently listing and accessing versions of Debian source packages
regardless of the specific storage layer the package is contained in,
which is detected automatically.

I separated verseek from pool because I figured it would be easier to
develop/debug this layer separately, and also that users would
potentially benefit from having `raw' access to the provided
functionality.

Currently, verseek supports 4 types of underlying storage:
A) plain directory: may contain multiple source packages, but only the most current version can be accessed
B) git: a git repository potentially containing multiple Debian packages
C) sumo: a Sumo arena potentially containing multiple Debian packages
D) git-single: a git repository containing only one auto-versioned Debian project

USAGE EXAMPLE

$ verseek git/pyhello --list
1.3
1.2
1.0

$ verseek git/pyhello 1.2

$ git/pyhello/pyhello
hello world 1.2

$ verseek git/pyhello

$ git/pyhello/pyhello
hello world 1.3

HOW IT WORKS

It is useful to understand how verseek works, even if just in
principle, in order to understand the implications for managing source
versions under various storage types.

A) plain directory

This is the simplest storage layer, and it doesn't do much besides
satisfying verseek's interface. When you `list' versions available in
a plain directory, you'll only get the latest version, which is
determined by parsing debian/changelog. Accordingly, this is the only
version you can seek to.

B) Git

In addition to being a useful storage layer in itself, this also
happens to be the base type from which all other supported storage
layers inherit. I will later describe the derived layers in respect to
how they are different from the base type.

* Listing: version lists are calculated by
	1) listing all commits in which path/debian/changelog changes:
	git-rev-list <branch> path/debian/changelog

	2) for each commit, extracting the version by parsing debian/changelog in those commits:
	git-cat-file blob <commit>:path/debian/changelog

* Seeking: implemented by checking out the commit in which the
changelog changed. Note that this checks out the entire git
repository, so you can't seek to different versions of different
packages in the same underlying git repository at the same time.

Since verseek checks out a specific commit rather than a branch, Git
will perform a `detached' checkout (HEAD is pointing directly to a
commit), while the current branch is preserved in VERSEEK_HEAD.
		
C) Sumo

Changes relative to Git storage:
* Operates on an open arena union path 

e.g.,
	$ verseek -l sumotest/arena/pyhello
	1.2
	1.1
	1.0

* We list commits in which debian/changelog changed *in the overlay*
Note that this means verseek won't see debian/changelog revisions in
the fat, so for example, if you want verseek to `see' the
debian/changelog you unpacked from a tarball, you'll have to `touch
arena/pyhello/debian/changelog` which will perform a copy-on-write to
the overlay.

* We use sumo-checkout instead of git-checkout. Under some conditions,
sumo-checkout may need a network connection to retrieve uncached
urls. Also note that locally generated thin branches will be checked
out much more quickly than remote thin branches (for which the journal
has to be replayed from the closest locally vailable fat commit).

D) git-single (derived from git)

Changes relative to Git storage:
- Uses autoversioning rather than revisions of debian/changelog to
list versions and to map versions to commits.  - After checking out
the commit for a version, verseek creates a dummy changelog. The
`release' field in the changelog is controlled by the `RELEASE'
environment variable, and defaults to `UNRELEASED'.
	
LIMITATIONS

verseek expects debian/control to exist in any version of the source
package, because this is the file verseek uses to identify that a path
is indeed a debian source in the first place.

If you seek back to a version that does not have debian/control -
verseek will get `stuck' on that version, and you won't be able to
seek to another version with verseek because it won't even recognize
the path as a valid Debian package.  Note, that the arena has to be
open.
