From c7e9b322916ef8f389080bd38334d03e22c36f50 Mon Sep 17 00:00:00 2001
From: "C. E. Ball" <ceball@gmail.com>
Date: Fri, 6 Apr 2018 10:55:18 +0100
Subject: [PATCH 1/3] Initial sketch of versioning workflow docs.

---
 README.md | 49 +++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 49 insertions(+)

diff --git a/README.md b/README.md
index 3820d129..6ff9dcc0 100644
--- a/README.md
+++ b/README.md
@@ -14,3 +14,52 @@ 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)
+
+## Usage
+
+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 autover.py into your project's git root directory and commit
+     to git.
+  
+  2. `import autover` and call `autover.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)
+or [depending on
+autover](https://github.com/ioam/autover/tree/master/examples/pkg_depend).

From 842fdc79aa533eb473b92439f0f566a4ec1e5dae Mon Sep 17 00:00:00 2001
From: "C. E. Ball" <ceball@gmail.com>
Date: Fri, 6 Apr 2018 11:00:05 +0100
Subject: [PATCH 2/3] Minor clarification [ci skip]

---
 README.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/README.md b/README.md
index 6ff9dcc0..ce0e0312 100644
--- a/README.md
+++ b/README.md
@@ -61,5 +61,5 @@ except:
 
 There are alternative ways to use autover, including [via
 param](https://github.com/ioam/autover/tree/master/examples/pkg_params)
-or [depending on
+(convenient if your project already depends on param) or [depending on
 autover](https://github.com/ioam/autover/tree/master/examples/pkg_depend).

From b85c911e276c7f12d16003c80aeea40d180e3c05 Mon Sep 17 00:00:00 2001
From: "C. E. Ball" <ceball@gmail.com>
Date: Fri, 6 Apr 2018 11:16:17 +0100
Subject: [PATCH 3/3] Added sketch of usage [ci skip]

---
 README.md | 21 ++++++++++++++++++---
 1 file changed, 18 insertions(+), 3 deletions(-)

diff --git a/README.md b/README.md
index ce0e0312..13257143 100644
--- a/README.md
+++ b/README.md
@@ -19,7 +19,7 @@ Authors: Jean-Luc Stevens, Chris Ball and James A. Bednar
 
 (some intro)
 
-## Usage
+## 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
@@ -27,10 +27,10 @@ follow the example [bundle
 autover](https://github.com/ioam/autover/tree/master/examples/pkg_bundle)
 package.
 
-  1. copy autover.py into your project's git root directory and commit
+  1. copy version.py into your project's git root directory and commit
      to git.
   
-  2. `import autover` and call `autover.get_setup_version(...)` in
+  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
@@ -63,3 +63,18 @@ 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).