From 29b2836c504baa66a54e8f32c4dedf56e19c9157 Mon Sep 17 00:00:00 2001
From: Carol Willing <carolcode@willingconsulting.com>
Date: Tue, 20 Sep 2016 12:23:19 -0700
Subject: [PATCH] Add wip upgrade doc

---
 docs/source/index.rst    |  2 ++
 docs/source/upgrading.md | 36 ++++++++++++++++++++++++++++++++++++
 2 files changed, 38 insertions(+)
 create mode 100644 docs/source/upgrading.md

diff --git a/docs/source/index.rst b/docs/source/index.rst
index fb69ebed..0d0f60c3 100644
--- a/docs/source/index.rst
+++ b/docs/source/index.rst
@@ -61,6 +61,7 @@ Contents
 * :doc:`spawners`
 * :doc:`services`
 * :doc:`config-examples`
+* :doc:`upgrading`
 * :doc:`troubleshooting`
 
 .. toctree::
@@ -72,6 +73,7 @@ Contents
    spawners
    services
    config-examples
+   upgrading
    troubleshooting
 
 
diff --git a/docs/source/upgrading.md b/docs/source/upgrading.md
new file mode 100644
index 00000000..f7675121
--- /dev/null
+++ b/docs/source/upgrading.md
@@ -0,0 +1,36 @@
+# Upgrading JupyterHub and its databases
+
+## Definitions
+db type: sqlite, postgres, mysql, others???
+db fields: individual fields in a database table
+
+## Basic use cases
+- [ ] Simple upgrade - no database fields changed; no db type change
+- [ ] Field changes  - database fields added, deleted or changed by a new JHub release/functionality; no db type change
+
+## More complex use cases
+- [ ] Field changes - database fields added, deleted or changed by user; no db type change
+- [ ] db type change (i.e. sqlite to postgres) - fields may or may not change; db type does change
+
+## Process
+- Remind admins to back up Hub databases
+- Possibly remind admins to make sure single user notebook data is saved/backed up
+- Admin notify users (if desired) of planned upgrade
+
+**Multi-step upgrade vs all at once**??
+- Migrate database type (Hub at same release level) user-initiated
+- Add/change/delete fields (Hub at same release level) user-initiated
+- Add/change/delete files (Hub initiated - in prep for JHub release upgrade)
+- Upgrade Hub to 0.7 after
+
+- Upgrade/changes to: CHP, authenticators, spawners
+
+## Other topics
+- limitations of sqlite upgrade
+- upgrade hub first or upgrade db first???
+
+## Tools
+- alembic
+- scripts
+- sqlalchemy?
+- db tools