Implement blackbox in Golang (#250)

* Initial release

docs/backwards-compatibility.md

@@ -0,0 +1,55 @@
+Backwards Compatibility
+=======================
+
+# Where is the configuration stored? .blackbox vs. keyrings/live
+
+Blackbox stores its configuration data in the `.blackbox` subdirectory.  Older
+repos use `keyrings/live`.  For backwards compatibility either will work.
+
+All documentation refers to `.blackbox`.
+
+You can convert an old repo by simply renaming the directory:
+
+```
+mv keyrings/live .blackbox
+rmdir keyrings
+```
+
+There is no technical reason to convert old repos except that it is less
+confusing to users.
+
+This change was made in commit 60e782a0, release v1.20180615.
+
+
+# How blackbox fines the config directory:
+
+## Creating the repo:
+
+`blackbox init` creates the config directory in the root
+of the repo.  Here's how it picks the name:
+
+- If `$BLACKBOX_TEAM` is set, `.blackbox-$BLACKBOX_TEAM` is used.
+- If the flag `--team <teamname>` is set, it uses `.blackbox-<teamname>`
+- Otherwise, it uses `.blackbox`
+
+When searching for the configuration directory, the following
+locations are checked. First match wins.
+
+- `.blackbox-$BLACKBOX_TEAM` (only if `$BLACKBOX_TEAM` is set)
+- The value of `--config value` (if the flag is set)
+- `$BLACKBOX_CONFIGDIR` (the preferred env. variable to use)
+- `$BLACKBOXDATA` (for backwards compatibility with v1)
+- `.blackbox`
+- `keyrings/live` (for backwards compatibility)
+
+NOTE: The env variables and `--config` should be set to the full path
+to the config directory (i.e.: `/Users/tom/gitstuff/myrepo/.blackbox`).
+If it is set to a relative directory (i.e. `.blackbox` or
+`../myrepo/.blackbox`) most commands will break.
+
+NOTE: Why the change from `$BLACKBOXDATA` to `$BLACKBOX_CONFIGDIR`?  We want
+all the env. variables to begin with the prefix `BLACKBOX_`.  If v1
+supported another name, that is still supported. If you are starting
+with v2 and have no other users using v1, please use the `BLACKBOX_`
+prefix.
+