[#315,cli][s]: command to add existing apps as heroku/git remotes loc…

…ally - fixes #315.

* Heavily update deploy instructions with section on upgrading code and config
  for existing sites (using new remotes command!)
* As a result of doc upgrade also introduced CHANGES.md to document database changes

CHANGES.md

@@ -0,0 +1,66 @@
+# Code
+
+Note: we haven't yet really done proper releases or tagging.
+
+## v3.1
+
+* Translation
+
+## v3.0 - February 2014
+
+Key focus of this release was to enable deployment and management of many
+"custom" censuses 
+
+[Github Milestone](https://github.com/okfn/opendatacensus/issues?milestone=5&state=closed)
+
+* Major internal code upgrade and refactor to support multiple instances
+* User authentication and separate user database
+* Core config in spreadsheet for easy administration
+
+## v2.1 - October 2014
+
+Focus of this release was frontend presentation.
+
+[Github Milestone](https://github.com/okfn/opendatacensus/issues?milestone=3&state=closed)
+
+## v2.0 - October 2014
+
+----
+
+# Database
+
+## Database v3 - Feb 18 2014
+
+Code Release: v3
+
+Code SHA: ac2aca9c1a08cde12c307166887693e9f3d4aa4f (last related commit)
+
+See also 97bee55339ecd4a50985d8d843817cb01312d768 for fields other than censusid.
+
+Introduction of fields to Submission table:
+
+* censusid
+* licenseurl
+* title
+* publisher
+* qualityinfo
+* qualitystructure
+
+Repurpose submitterid. Existing submitterid values are no longer valid so you
+MUST move any existing submitterid column to e.g. submitterid_old and introduce
+new submitterid column (note we do not use submitterid yet so nothing will
+break right now if you don't do this but will cause problems in the future).
+
+Introduction of fields to Entries table:
+
+* censusid
+* licenseurl
+* title
+* publisher
+* qualityinfo
+* qualitystructure
+
+## Database v2
+
+## Database v1
+

bin/census

@@ -17,8 +17,9 @@ var argv = optimist
       '',
       'Where command is one of:',
       '',
-      '  create {slug}   Interactively create a census deployment named slug',
-      '  config {slug}   Set environment based config for an existing census deployment',
+      '  create {slug}  Interactively create a census deployment named slug',
+      '  config {slug}  Set environment based config for an existing census deployment',
+      '  remotes        Sync your local list of heroku remotes from the instance db',
     ].join(os.EOL)
   )
   .alias('h', 'help').describe('h', 'print usage')

doc/deploy.md

@@ -1,8 +1,15 @@
-## Creating a New Census App
+# System Adminstration of Census Instances
 
 These instructions are for Developers. It assumes you already have the code
 installed on your machine.
 
+Before you start:
+
+* Check you have a Google account and that this account has access to the
+  [census instance spreadsheet][instance]
+
+## Deploying a New Census Instance
+
 If you are **not** a developer but want a Census booted please visit and make a
 request <http://meta.census.okfn.org/request/>
 
@@ -11,10 +18,8 @@ request <http://meta.census.okfn.org/request/>
 [instance]: https://docs.google.com/a/okfn.org/spreadsheet/ccc?key=0AqR8dXc6Ji4JdHZoLXhLMjNVNjVPQzVlaU0tSjNUYlE#gid=0
 [city-config]: https://docs.google.com/a/okfn.org/spreadsheet/ccc?key=0AqR8dXc6Ji4JdE16XzdsOFgtWGpGVVJ3YVRIQW1jZkE&usp=drive_web
 
-## Before you start
+### Before you start
 
-* Check you have a Google account and that this account has access to the
-  [census instance spreadsheet][instance]
 * Identify the `slug` for your app. It will usually be `{2-digit-iso}-{type}`
   where {type} is one of `city` or `region`. The site will then be online at
   `{slug}.census.okfn.org` (the "`site_url`")
@@ -25,7 +30,7 @@ IMPORTANT: to make a Google Spreadsheet 'Public on the Web' you must:
 * Go to sharing and make world readable
 * Go to File Menu => "Publish to the Web" and click "Start Publishing"
 
-## Step-by-Step
+### Step-by-Step
 
 * Open the [census instance spreadsheet][instance]. You should add relevant
   info to this as you do next steps.
@@ -69,10 +74,47 @@ Optional:
 
      `heroku domains:add {slug}.census.okfn.org`
 
-### TODO
+## Managing Existing Instances
+
+Before managing an existing instance you must make sure you have the heroku
+remote setup locally. To setup all the heroku remotes for all instances in one
+step do:
+
+    bin/census remotes
+
+### Updating the (Environment) Config for an Instance
+
+Most config for censuses lives in the config spreadsheet for that instance and
+can be managed by a Census Administrator. However, some config lives in the
+Environment (mainly private data). This config data (which is either generated
+or pulled from the Instances Database Spreadsheet) can be updated by doing:
+
+    bin/census config {census-id}
+
+For example, to upgrade the national census config you would do:
+
+    bin/census config national
+
+## Upgrading (Code) a Census Instance
+
+**WARNING:** Make sure you've performed any required upgrades to the "database"
+spreadsheets. For example, fields may have been added or removed. At present
+all database migrations have to be performed manually. See CHANGES.md for a
+full list of database changes.
+
+To upgrade the code for an instance to the current master:
+
+    git push {SLUG}
+
+For example, to upgrade demo to latest master do:
+
+    git push demo
+
+To upgrade the code for an instance to a specific branch:
+
+    git push {SLUG} {BRANCH}
 
-Document key config that needs to be set e.g.
+For example, to push the production branch to demo do:
 
-* site_url
-* configUrl
+    git push demo production
 

lib/cli.js

@@ -39,24 +39,33 @@ try {
   throw 'Deploy config at .deploy.js does not exist or is wrongly formatted';
 }
 
-function getInstanceInfo(id, cb) {
+function getAllInstanceInfo(cb) {
   var backend = new model.Backend({
     key: deployConfig.db_key,
     user: deployConfig.user,
     password: deployConfig.password
   });
   backend.login(function(err) {
     assert(!err, 'Failed to login');
-    backend.get(deployConfig.db_sheet_index, {censusid: id}, function(err, instanceInfo) {
+    backend.select(deployConfig.db_sheet_index, {}, function(err, instanceInfo) {
       assert(!err, err);
-      assert(instanceInfo, 'No instance found with id ' + id);
-      // var siteUrl = 'http://opendatacensus-SLUG.herokuapp.com/'.replace(/SLUG/g, instanceInfo.censusid);
-      instanceInfo.siteUrl = 'http://SLUG.census.okfn.org'.replace(/SLUG/g, instanceInfo.censusid);
+      assert(instanceInfo, 'No data found');
       cb(err, instanceInfo)
     });
   });
 }
 
+function getInstanceInfo(id, cb) {
+  getAllInstanceInfo(function(err, instances) {
+    instanceInfo = instances.filter(function(inst) {
+      return (inst.censusid === id);
+    });
+    instanceInfo = instanceInfo.length > 0 ? instanceInfo[0] : null;
+    assert(instanceInfo, 'No instance found with id ' + id);
+    cb(err, instanceInfo)
+  });
+}
+
 exports.create = function(id) {
   assert(id, 'id must be a string');
 
@@ -82,7 +91,7 @@ exports.create = function(id) {
     console.log([
       'Your new census instance is live at',
       '',
-      instanceInfo.siteUrl,
+      instanceInfo.siteurl,
       ''
       ].join('\n')
     )
@@ -113,7 +122,17 @@ function getConfCmd(instanceInfo) {
     confcmd += ' ';
   })
   // will probably override in config but set a default value so that login works out of the box
-  confcmd += 'SITE_URL=' + instanceInfo.siteUrl + ' ';
+  confcmd += 'SITE_URL=' + instanceInfo.siteurl + ' ';
   return confcmd;
 }
 
+exports.remotes = function() {
+  getAllInstanceInfo(function(err, instances) {
+    instances.forEach(function(inst) {
+      cmd = 'heroku git:remote -r SLUG -a opendatacensus-SLUG'.replace(/SLUG/g, inst.censusid);
+      console.log(cmd);
+      execSync(cmd);
+    });
+  });
+}
+