Documentation: installation and setup instructions, and some notes

README.md

@@ -4,9 +4,65 @@ This is work-in-progress documentation for the work-in-progress package manager
 (the name is also a work-in-progress) As such, everything here is subject to
 change.
 
-# Package
+# Installation and Testing
 
-A _package_ consists of an archive containing files to be installed.
+1. Clone blender and checkout the [`soc-2017-package_manager` branch](https://developer.blender.org/diffusion/B/browse/soc-2017-package_manager/).
+
+	git clone git://git.blender.org/blender.git
+	git checkout soc-2017-package_manager
+
+2. [Compile](https://wiki.blender.org/index.php/Dev:Doc/Building_Blender).
+3. Clone the [package manager addon repository](https://developer.blender.org/diffusion/BPMA/repository):
+
+	git clone git://git.blender.org/blender-package-manager-addon.git
+
+4. Install the addon. Copy (or symlink) the `package_manager` directory
+   contained *within* the cloned repository into
+   `/path/to/blender/build/bin/2.78/scripts/addons/`
+5. Run blender
+6. Open the user preferences and switch to the "Packages" section.
+
+The default repository can currently be changed in the addon's preferences
+section (currently only accessible in the "Addons" section).
+
+A local repository can be generated with the `generate_repository` script found
+in the addon repository. Example usage:
+
+	./generate_repository /path/to/packages --baseurl 'http://localhost/'
+
+This will produce a `repo.json` file in the current directory, which can then
+be copied to the server.  The baseurl is prepended to the filename of each
+package to form the package's url (so for example, `http://localhost/node_wrangler.py`).
+
+
+# Known limitations
+
+Things which are known to be bad, but are planned to get better
+
+* No progress display
+* No installed/available/upgradeable filtering
+* Asynchronous operators can be run multiple times at once
+* Not more than one repository can be used at once
+* Only the latest version of a package can be installed and uninstalled 
+
+# Notes
+
+Packages which are installed on disk but aren't present in a known repository
+are listed as 'installed' without an option to uninstall. This is so that it's
+always possible to undo an uninstall. My intention is to eventually make uninstalls
+undo-able until blender is restarted by moving the uninstalled files to a cache
+directory which is flushed on startup and/or exit.
+
+Packages are identified by their name. This could of course cause issues if two
+different packages end up with the same name. As it seems 2.8 will break many
+addons anyway, perhaps we can add a required metadata field that allows for
+more reliable unique identification?
+	
+# Terminology
+
+## Package
+
+A _package_ consists of a single file, or a zip archive containing files to be installed.
 
 Note:  
 I think it would be good to always store `bl_info` metadata with the package,
@@ -15,7 +71,7 @@ non-addons remains an open question (perhaps we can always include an
 `__init__.py` even in non-addon packages?)
 
 
-# Repository
+## Repository
 
 A _repository_ consists of a directory containing a "repo.json" file.  This
 repo.json file contains metadata describing each package (`bl_info`) and where
@@ -25,7 +81,7 @@ A repo.json file may currently be generated from a directory of addons by
 running `blenderpack.py <path/to/addon/dir>`.
 
 
-# Client
+## Client
 
 Clients "use" a repository by including its repo.json in packages listed in 
 Clients can be configured to use multiple repositories at once.
@@ -35,13 +91,13 @@ repo.json containing installed packages.
 
 Clients can take the following actions:
 
-## Install
+### Install
 
 _Installing_ means downloading a single package, adding it to the local
 repository, and extracting/copying the package's file(s) to their
 destination(s).
 
-## Uninstall
+### Uninstall
 
 _Uninstalling_ means deleting a single package's files, then removing it from
 the local repository.
@@ -50,14 +106,13 @@ Note:
 If some packages store user-created data (e.g. preferences), we may want to
 preserve that somehow.
 
-## Upgrade
+### Upgrade
 
-_Upgrading_ means looking for newer addons with the same names as installed
-addons **from the same repository**.
+_Upgrading_ means looking for and installing newer addons with the same names as installed
+addons.
 
-## Refresh
+### Refresh
 
 _Refreshing_ means checking for modifications to the `repo.json`s of the enabled
-repositories. If there are modifications, then download them.
-This will be done automatically before an _Update_.
+repositories, and new packages which may have appeared on disk.