Upgrade guide for v0.2.0

docs/upgrade-guides/0.2.0.md

@@ -0,0 +1,108 @@
+# Updating js-bigchaindb-driver from v0.1.x to v0.2.0
+
+The latest version of js-bigchaindb-driver contains breaking changes to its
+external API. In this document, we enumerate all changes to allow you to make
+upgrades efficiently.
+
+Note that upgrading the js-bigchaindb-driver to v0.2.0 was done to enable
+functionality included in the latest (v1.0) BigchainDB release.  A full list of
+BigchainDB v1.0's breaking changes can be found
+[here](https://github.com/bigchaindb/bigchaindb/blob/17913dca682ff105540c0ea73365f1763efc2083/docs/upgrade-guides/v0.10--%3Ev1.0.md).
+Note that v1.0 [contains breaking changes to its core data
+models](https://github.com/bigchaindb/bigchaindb/blob/17913dca682ff105540c0ea73365f1763efc2083/docs/upgrade-guides/v0.10--%3Ev1.0.md#breaking-changes-to-the-data-model).
+
+This document will just go into the very specific breaking changes affecting
+the JavaScript driver.
+
+
+### Breaking changes to js-bigchaindb-driver's APIs
+
+#### Output amount is now a string
+
+```js
+// old
+export default function makeOutput(condition, amount = 1) {}
+
+// new
+export default function makeOutput(condition, amount = '1') {}
+```
+
+
+#### Update to Crypto-Conditions version 2
+
+All conditions or fulfillments passed manually to the driver now need to comply
+with ILP's Crypto-Condition version 2 specification.  For more information,
+[see the updated
+specification](https://tools.ietf.org/html/draft-thomas-crypto-conditions-02)
+or checkout the [latest reference implementation of Crypto-Conditions in
+JavaScript](https://github.com/interledgerjs/five-bells-condition).
+
+
+#### Several `Connection` methods now require positional arguments
+
+##### `Connection.listBlocks`
+
+```js
+// old
+new Connection(PATH).listBlocks({ tx_id, status })
+
+// new
+new Connection(PATH).listBlocks(transactionId, status)
+```
+
+
+##### `Connection.listOutputs`
+
+```js
+// old
+new Connection(PATH).listOutputs({ public_key, unspent })
+
+// new
+new Connection(PATH).listOutputs(publicKey, spent)
+```
+
+**NOTE:** The `unspent` flag has been inversed. This is inline [with breaking
+changes to BigchainDB
+v1.0](https://github.com/bigchaindb/bigchaindb/blob/17913dca682ff105540c0ea73365f1763efc2083/docs/upgrade-guides/v0.10--%3Ev1.0.md#get-apiv1outputs).
+
+
+##### `Connection.listTransactions`
+
+```js
+// old
+new Connection(PATH).listTransactions({ asset_id, operation })
+
+// new
+new Connection(PATH).listTransactions(assetId, operation)
+```
+
+
+### Newly added endpoints
+
+##### `Connection.searchAsset`
+
+```js
+// new
+new Connection(PATH).searchAsset(search)
+```
+
+A querying interface to text-search all assets in BigchainDB. For more
+documentation, [see BigchainDB's HTTP
+API](https://docs.bigchaindb.com/projects/server/en/latest/http-client-server-api.html#assets).
+
+
+### Newly available bundles and CDN hosting
+
+The driver is now bundled automatically each time we publish it to npm.com.  We
+now ship packages for `commonjs`, `commonjs2`, `amd`, `umd`, `window` and
+node.js. Thanks to unpkg.com, we're also able to provide all these packages on
+a CDN. A link to all the bundles can be found
+[here](https://unpkg.com/bigchaindb-driver@0.2.0/dist/browser/).
+
+
+A few notes:
+
+- Adjust version number in link as appropriate
+- only include `bigchaindb-driver.*.min.js`, but now everything `bundle.*`.
+  This is [a known
+  issue](https://github.com/bigchaindb/js-bigchaindb-driver/issues/66).