Initial sketch of versioning docs.

README.md

@@ -14,3 +14,67 @@ Autover provides:
      script](https://github.com/ioam/autover/blob/master/scripts/autover).
 
 Authors: Jean-Luc Stevens, Chris Ball and James A. Bednar
+
+# Versioning
+
+(some intro)
+
+## Installing
+
+The expected way for your-package to use autover is by bundling
+version.py.  An outline of how to do this is below, but you can also
+follow the example [bundle
+autover](https://github.com/ioam/autover/tree/master/examples/pkg_bundle)
+package.
+
+  1. copy version.py into your project's git root directory and commit
+     to git.
+
+  2. `import version` and call `version.get_setup_version(...)` in
+     your `setup.py` to get up to date version.
+
+  3. make sure at package time that the `.version` json file is included
+     in your package e.g. by adding `your-package/.version` to
+     `MANIFEST.in` and `include_package_data=True` in
+     `setup()`. (`version.py` will be included automatically unless you
+     do something to stop that.)
+
+  4. put the following `in your-package/__init__.py`:
+
+```python
+try:
+    import autover
+    __version__ = autover.Version(...)
+except:
+    import os, json
+    __version__ = json.load(... '.version')
+```
+
+     The first path above (`import autover`) is for developers who are
+     either in the git repository, or have done a `python setup.py
+     develop` install, or have the git repository on their
+     `PYTHONPATH`. I.e. if `import your-package` from the git repo is
+     possible, so is `import autover`. The second path is for people
+     who are installing a `your-package` package: no autover present
+     or needed, because a `.version` file is present in the package.
+
+
+There are alternative ways to use autover, including [via
+param](https://github.com/ioam/autover/tree/master/examples/pkg_params)
+(convenient if your project already depends on param) or [depending on
+autover](https://github.com/ioam/autover/tree/master/examples/pkg_depend).
+
+
+## Using
+
+If you tag your repo (e.g. `git tag -a v0.0.1 -m "some message"`),
+autover will then provide up to date, useful versions from then on. In
+this case, the version will be reported as `v0.0.1`. If you
+subsequently add a commit after this tag, the version will be reported
+as `v0.0.1post1+g842fdc7` (where `842fdc7` is the commit's SHA).
+
+Note: ? tags to use as the basis for releases should be on master.
+
+Autover gets the version via `git describe` where possible. Otherwise,
+it uses a simple json file (`your-package/.version`) to store the
+version (e.g. for generated packages).