add errata page for release

2 files changed, 45 insertions, 9 deletions

diff --git a/doc/assistant.mdwn b/doc/assistant.mdwn
index be67213f7..574607fa5 100644
--- a/doc/assistant.mdwn
+++ b/doc/assistant.mdwn
@@ -3,14 +3,13 @@ removable drives, and cloud services, which
 it keeps synchronised, so its contents are the same everywhere.
 It's very easy to use, and has all the power of git and git-annex.
 
-## installation
+Note that the git-annex assistant is still beta quality code. See
+[[the_errata]] for known infelicities.
 
-The git-annex assistant comes as part of git-annex.
-See [[install]] to get it installed.
+## installation
 
-Note that the git-annex assistant is still beta quality code.
-(And it's not yet in the released version of git-annex.
-That will change soon!)
+The git-annex assistant comes as part of git-annex, starting with version
+3.20120924. See [[install]] to get it installed.
 
 ## quick start
 
@@ -20,7 +19,7 @@ your system's list of applications.
 [[!img assistant/menu.png]]
 [[!img assistant/osx-app.png]]
 
-It'll prompt you to set up the folder:
+It'll prompt you to set up a folder:
 
 [[!img assistant/makerepo.png]]
 
@@ -35,10 +34,10 @@ interface to add repositories and control the git-annex assistant.
 * Want to make two nearby computers share the same synchronised folder?
   Follow the [[pairing_walkthrough]].
 
-## command line start
+## command line startup
 
 The git-annex assistant will automatically be started when you log in to
-desktop environments like Gnome, XFCE, and KDE, and the menu item
+desktop environments like Mac OS X, Gnome, XFCE, and KDE, and the menu item
 shown above can be used to open the webapp. On other systems, you may need
 to start it by hand.
 
diff --git a/doc/assistant/errata.mdwn b/doc/assistant/errata.mdwn
new file mode 100644
index 000000000..a4732a0d7
--- /dev/null
+++ b/doc/assistant/errata.mdwn
@@ -0,0 +1,37 @@
+## version 3.20120924
+
+This is the first beta release of the git-annex assistant.
+
+In general, anything you can configure with the assistant's web app
+will work. Some examples of use cases supported by this release include:
+
+* [[Pairing|pairing_walkthrough]] two computers that are on the same local
+  network (or VPN) and automatically keeping the files in the annex in
+  sync as changes are made to them.
+* Cloning your repository to removable drives, USB keys, etc. The assistant
+  will notice when the drive is mounted and keep it in sync.
+  Such a drive can be stored as an offline backup, or transported between
+  computers to keep them in sync.
+* Cloning your repository to a remote server, running ssh, and uploading
+  changes made to your files to the server. There is special support
+  for using the rsync.net cloud provider this way, or any shell account
+  on a typical unix server, such as a Linode VPS can be used.
+
+The following are known limitations of this release of the git-annex
+assistant:
+
+* On Mac OSX and BSD operating systems, the assistant uses kqueue to watch
+  files. Kqueue has to open every directory it watches, so too many
+  directories will run it out of the max number of open files (typically
+  1024), and fail. See [[bugs/Issue_on_OSX_with_some_system_limits]]
+  for a workaround.
+* In order to ensure that all multiple repositories are kept in sync,
+  each computer with a repository must be running the git-annex assistant.
+* The assistant does not yet always manage to keep repositories in sync
+  when some are hidden from others behind firewalls.
+* If a file is checked into git as a normal file and gets modified
+  (or merged, etc), it will be converted into an annexed file. So you
+  should not mix use of the assistant with normal git files in the same
+  repository yet.
+* If you `git annex unlock` a file, it will immediately be re-locked.
+  See [[bugs/watcher_commits_unlocked_files]].