From 3e02a2df668b6ba636deb6da81acc4223399dd2b Mon Sep 17 00:00:00 2001 From: Bryan Burgers Date: Sun, 12 Feb 2017 15:33:12 -0600 Subject: [PATCH] Bump version to 1.0.0 Major breaking API changes happened in PRs #153, #161, and #163. According to semver, there should be a major version number bump because of those changes. --- MIGRATING.md | 237 +++++++++++++++++++++++++++++++++++++++++++++++++++ README.md | 7 ++ package.json | 7 +- 3 files changed, 248 insertions(+), 3 deletions(-) create mode 100644 MIGRATING.md diff --git a/MIGRATING.md b/MIGRATING.md new file mode 100644 index 0000000..aa67515 --- /dev/null +++ b/MIGRATING.md @@ -0,0 +1,237 @@ +# Migrating + +Many core APIs changed betwen v0.2.21 and v1.0.0. This document describes how +to upgrade your application or library to use the new APIs when upgrading to +dbus 1.0.0. + + +## Clients + +Migrating node applications and libraries that use this module as a DBus client. + +### Getting a bus + +In version 1.0.0, you no longer need to instantiate an instance of DBus in +order to get a Bus instance. + +v0.2.21: + +``` +// v0.2.21 +var DBus = require('dbus'); +var dbus = new DBus(); +var bus = dbus.getBus('session'); +``` + +v1.0.0: + +``` +// v1.0.0 +var DBus = require('dbus'); +var bus = DBus.getBus('session'); +``` + +### Calling a method + +In version 1.0.0, calling a method on a DBus service uses a common node +callback pattern where the first parameter is an error and the second is the +result. + +v0.2.21: + +``` +// v0.2.21 +interface.Add.timeout = 1000; +interface.Add.error = function(err) { + // handle error +}; +interface.Add.finish = function(result) { + assert(result === 3); +}; +interface.Add(1, 2); +``` + +v1.0.0: + +``` +// v1.0.0 +interface.Add(1, 2, { timeout: 1000 }, function(err, result) { + if (err) { + // handle error + } + + assert(result === 3); +}); +``` + +Timeout may be omitted if it is not needed. + +``` +// v1.0.0 +interface.Add(1, 2, function(err, result) { + if (err) { + // handle error + } + + assert(result === 3); +}); +``` + + +## Services + +Migrating node applications and libraries that use this module to create DBus +services. + +### Creating a service + +In version 1.0.0, you no longer need to instantiate an instance of DBus in +order to get a Service instance. + +v0.2.21: + +``` +// v0.2.21 +var DBus = require('dbus'); +var dbus = new DBus(); +var service = dbus.registerService('session', 'test.dbus.TestService'); +``` + +v1.0.0: + +``` +// v1.0.0 +var DBus = require('dbus'); +var service = DBus.registerService('session', 'test.dbus.TestService'); +``` + +### Responding to a method + +In v1.0.0, methods use a more typical node callback pattern where an error is +the first parameter and a result is the second parameter. + +v0.2.21: + +``` +// v0.2.21 +service.addMethod('MyMethod', { out: DBus.Define(Number) }, function(callback) { + callback(3); +}); +``` + +v1.0.0: + +``` +// v1.0.0 +service.addMethod('MyMethod', { out: DBus.Define(Number) }, function(callback) { + callback(null, 3); // return the result as the second parameter +}); +``` + +### Throwing an error from a method + +In v1.0.0, errors can include both the DBus name and a message. Previously, +they could only include the DBus name. + +v0.2.21: + +``` +// v0.2.21 +service.addMethod('MyMethod', { out: DBus.Define(Number) }, function(callback) { + callback(new Error('test.dbus.TestService.Error'); +}); +``` + +v1.0.0: + +``` +// v1.0.0 +service.addMethod('MyMethod', { out: DBus.Define(Number) }, function(callback) { + callback(new DBus.Error('test.dbus.TestService.Error', 'Human-readable error message')); +}); +``` + +Using a standard error is still possible, and defaults to +[DBUS_ERROR_FAILED][dbuserror]. + +``` +// v1.0.0 +service.addMethod('MyMethod', { out: DBus.Define(Number) }, function(callback) { + // Error name defaults to the generic 'org.freedesktop.DBus.Error.Failed' + callback(new Error('Human-readable error message')); +}); +``` + +### Responding to a property + +In v1.0.0, properties use a more typical node callback pattern where an error +is the first parameter and a result is the second parameter. + +v0.2.21: + +``` +// v0.2.21 +service.addProperty('MyProperty', { + type: DBus.Define(Number), + getter: function(callback) { + callback(3); + } +}); +``` + +v1.0.0: + +``` +// v1.0.0 +service.addProperty('MyProperty', { + type: DBus.Define(Number), + getter: function(callback) { + callback(null, 3); // Return the result as the second parameter. + } +}); +``` + +### Throwing an error from a property + +In v1.0.0, errors can include both the DBus name and a message. Previously, +they could only include the DBus name. + +v0.2.21: + +``` +// v0.2.21 +service.addProperty('MyProperty', { + type: DBus.Define(Number), + getter: function(callback) { + callback(new Error('test.dbus.TestService.Error'); + } +}); +``` + +v1.0.0: + +``` +// v1.0.0 +service.addProperty('MyProperty', { + type: DBus.Define(Number), + getter: function(callback) { + callback(new DBus.Error('test.dbus.TestService.Error', 'Human-readable error message')); + } +}); +``` + +Using a standard error is still possible, and defaults to +[DBUS_ERROR_FAILED][dbuserror]. + +``` +// v1.0.0 +service.addProperty('MyProperty', { + type: DBus.Define(Number), + getter: function(callback) { + // Error name defaults to the generic 'org.freedesktop.DBus.Error.Failed' + callback(new Error('Human-readable error message')); + } +}); +``` + +[dbuserror]: https://dbus.freedesktop.org/doc/api/html/group__DBusProtocol.html#gabb62fd6340d0787fbd56ff8dd2f326c7 diff --git a/README.md b/README.md index 4c316ad..a484257 100644 --- a/README.md +++ b/README.md @@ -13,6 +13,12 @@ $ npm install dbus ## How To Build To build, do: `node-gyp configure build` or `npm install`. +## Migrating to version 1.0 + +The API changed between version 0.2.21 and version 1.0.0. See +[migrating][migrating] for information on how to migrate your application to +the new API. + ## Dependencies ### General @@ -406,3 +412,4 @@ TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. [spec]: https://dbus.freedesktop.org/doc/dbus-specification.html +[migrating]: MIGRATING.md diff --git a/package.json b/package.json index e7a09da..bf059a9 100644 --- a/package.json +++ b/package.json @@ -1,10 +1,11 @@ { "name": "dbus", - "version": "0.2.22", + "version": "1.0.0", "description": "A D-Bus binding for Node", "author": "Shouqun Liu ", "contributors": [ - "Fred Chien " + "Fred Chien ", + "Bryan Burgers " ], "license": "MIT", "repository": { @@ -12,7 +13,7 @@ "url": "git://github.com/Shouqun/node-dbus.git" }, "engines": { - "node": ">= 0.8.0" + "node": ">= 0.12.0" }, "main": "./lib/dbus", "scripts": {