Merge pull request #164 from bryanburgers/v1.0.0

Bump version to 1.0.0

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

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
@@ -414,3 +420,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

package.json

@@ -1,18 +1,19 @@
 {
   "name": "dbus",
-  "version": "0.2.22",
+  "version": "1.0.0",
   "description": "A D-Bus binding for Node",
   "author": "Shouqun Liu <[email protected]>",
   "contributors": [
-    "Fred Chien <[email protected]>"
+    "Fred Chien <[email protected]>",
+    "Bryan Burgers <[email protected]>"
   ],
   "license": "MIT",
   "repository": {
     "type": "git",
     "url": "git://github.com/Shouqun/node-dbus.git"
   },
   "engines": {
-    "node": ">= 0.8.0"
+    "node": ">= 0.12.0"
   },
   "main": "./lib/dbus",
   "scripts": {