release notes for tomorrow's release

debian/changelog

@@ -1,12 +1,13 @@
 git-annex (3.20121018) UNRELEASED; urgency=low
 
-  * assistant: Can use XMPP to notify other nodes about pushes, as well
+  * assistant: Can use XMPP to notify other nodes about pushes made to other
-    as pushing to them over XMPP.
+    repositories, as well as pushing to them directly over XMPP.
-  * webapp: Now supports pairing over XMPP.
+  * wepapp: Added an XMPP configuration interface.
-  * assistant: Now drops non-preferred content.
+  * webapp: Supports pairing over XMPP, with both friends, and other repos
-  * assistant: Now notices, and applies config changes 
+    using the same account.
-    as they are made to the git-annex branch, including config changes
+  * assistant: Drops non-preferred content when possible.
-    pushed in from remotes.
+  * assistant: Notices, and applies config changes as they are made to
+    the git-annex branch, including config changes pushed in from remotes.
   * git-annex-shell: GIT_ANNEX_SHELL_DIRECTORY can be set to limit it
     to operating on a specified directory.
   * webapp: When setting up authorized_keys, use GIT_ANNEX_SHELL_DIRECTORY.

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.
 
-Note that the git-annex assistant is still beta quality code. See
-[[the_errata|errata]] for known infelicities.
-
 ## installation
 
 The git-annex assistant comes as part of git-annex, starting with version
-3.20120924. It is still under heavy development, but the basics work well.
+3.20120924. See [[install]] to get it installed.
-See [[install]] to get it installed.
+
+Note that the git-annex assistant is still beta quality code. See
+the [[release_notes]] for known infelicities and upgrade instructions.
 
 ## quick start
 

doc/assistant/release_notes.mdwn

@@ -1,3 +1,49 @@
+## version 3.20121012
+
+This is a major upgrade of the git-annex assistant, which is still in beta.
+
+In general, anything you can configure with the assistant's web app
+will work. Some examples of use cases supported by this release include:
+
+* [[Sharing repositories with friends|share_with_a_friend_walkthrough]]
+  contacted through a Jabber server (such as Google Talk).
+* Setting up cloud repositories, that are used as backups, archives,
+  or transfer points between repositories that cannot directly contact
+  one-another.
+* [[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.
+
+The following upgrade notes apply if you're upgrading from a previous version:
+
+* For best results, edit the configuration of repositories you set
+  up with older versions, and place them in a repository group.
+  This lets the assistant know how you want to use the repository; for backup,
+  archival, as a transfer point for clients, etc. Go to Configuration ->
+  Manage Repositories, and click in the "configure" link to edit a repository's
+  configuration.
+* If you set up a cloud repository with an older version, and have multiple
+  clients using it, you are recommended to configure an Jabber account,
+  so that clients can use it to communicate when sending data to the
+  cloud repository. Configure Jabber by opening the webapp, and going to
+  Configuration -> Configure jabber account
+* When setting up local pairing, the assistant did not limit the paired
+  computer to accessing a single git repository. This new version does,
+  by setting GIT_ANNEX_SHELL_DIRECTORY in `~/.ssh/authorized_keys`.
+
+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.
+
 ## version 3.20121009
 
 This is a maintenance release of the git-annex assistant, which is still in