From 59321cb4058c3733ab68f1ceeccd99cad8cc266b Mon Sep 17 00:00:00 2001 From: Francis Gulotta Date: Thu, 16 Jun 2016 23:56:28 -0400 Subject: [PATCH] Prep for 4.0 with upgrade guide and unified change log --- .npmignore | 1 + README.md | 4 ++-- UPGRADE_GUIDE.md | 57 ++++++++++++++++++++++++++++++++++++++++++++++++ changelog.md | 37 ++++++++++++------------------- package.json | 4 ++-- 5 files changed, 76 insertions(+), 27 deletions(-) create mode 100644 UPGRADE_GUIDE.md diff --git a/.npmignore b/.npmignore index 8017db067..fa9807725 100644 --- a/.npmignore +++ b/.npmignore @@ -10,6 +10,7 @@ examples/ Gruntfile.js PUBLISHING.md test/ +UPGRADE_GUIDE.md # MIRRORED FROM .gitignore PLEASE MAINTAIN *.node diff --git a/README.md b/README.md index 0d097d043..9fcddbd52 100644 --- a/README.md +++ b/README.md @@ -14,9 +14,9 @@ If you'd like to contribute please take a look at [contribution guide](CONTRIBUT # Which version of Serialport would you like documentation for? -You're reading the README for the master branch of serialport. You probably want to be looking at the README of our latest release. See our [change log](changelog.md) for what's new. +You're reading the README for the master branch of serialport. You probably want to be looking at the README of our latest release. See our [change log](changelog.md) for what's new and our [upgrade guide](UPGRADE_GUIDE.md) for a walk through on what to look out for between major versions. - - [`serialport@4.0.0-beta3` docs are here](https://github.com/EmergingTechnologyAdvisors/node-serialport/blob/4.0.0-beta3/README.md) it is the latest `4.x` releases. + - [`serialport@4.0.0` docs are here](https://github.com/EmergingTechnologyAdvisors/node-serialport/blob/4.0.0/README.md) it is the latest `4.x` releases. - [`serialport@3.1.2` docs are here](https://github.com/EmergingTechnologyAdvisors/node-serialport/blob/3.1.2/README.md) it is the latest `3.x` releases. - [`serialport@2.1.2` docs are here](https://github.com/EmergingTechnologyAdvisors/node-serialport/blob/2.1.2/README.md) it was the last `2.x` release - [`serialport@1.7.4` docs are here](https://github.com/EmergingTechnologyAdvisors/node-serialport/blob/v1.7.4/README.md) it was the last `1.x` release diff --git a/UPGRADE_GUIDE.md b/UPGRADE_GUIDE.md new file mode 100644 index 000000000..074fb8e29 --- /dev/null +++ b/UPGRADE_GUIDE.md @@ -0,0 +1,57 @@ +Upgrading from 3.x to 4.x +------------- +4.x brings a lot of changes please see the [changelog](./changelog.md) for the full list of changes. We'll review the api and behavior changes here. + +The constructor has changed. We've removed an argument, changed how errors are thrown and it is returned when you `require('serialport');` + + - Requiring `serialport` now returns the SerialPort constructor function instead of a factory object. `SerialPort.SerialPort` is now depreciated. + - `SerialPort` constructor now throws on argument errors immediately. + - Removed `openImmediately` from the constructor's api, the functionality is now named `autoOpen` on the options object. + - Removed extraneous flow control settings from the `flowControl` option, use the specific options to set these flags now. + - Removed undocumented callbacks from the options object `disconnectedCallback` and `dataCallback` + + Write had a major change + + - `.write(writeCallback)` now only calls it's callback once after the entire write operation, it used to be called for each write cycle and return the bytes written. This reduces the number of callbacks by hundreds of thousands over a megabyte at low bandwidth. + +Callbacks changed a little + + - All callbacks are called in the context of the port, `this` now equals the port. + - Disconnections now always attempt to close the port, and you'll always get a `close` event after a `disconnect` event + +Renamed our binaries + + - Reanmed `serialportlist` to `serialport-list` + - Renamed `serialportterm` to `serialport-term` + +We fixed a bunch of bugs too + + - [unix] `.drain` and `.set` now properly report errors + - [windows] Fixed a bug where we weren't properly opening ports (provides better support virtual com ports too) thanks to @RogerHardiman + - [windows] known issue `lock` false doesn't work (no change in behavior) + +And added a new features + + - [unix] Ports are now locked by default with the new `lock` options matches windows default behavior + - [windows] `.update()` now supports windows for changing baud rates + +Upgrading from 2.x to 3.x +------------- +3.0 brought a single major breaking change and a lot of minor improvements. + +We stopped removing event listeners, if you wrote code to work around that, we're sorry we made you do it. + +- `close` and `disconnect` events no longer call `removeAllListeners` and removes your event listeners. This was particularly bad for the `error` event. This is the only change and if you didn't have a special code to deal with this behavior you should probably upgrade from v2.1.2 + +New Features + + - Added support for node 6.0 + - Update the cli tools. serialportterm can now list ports, serialportlist can now output in different formats + - [unix] Better unix error messages + +Fixed bugs + + - [linux] bug fix in `.list()` where we weren't filtering out non block devices that are named like serial ports + - [unix] Update now has less memory leaks, documentation and better error messages + - [windows] Better error messages for opening ports + diff --git a/changelog.md b/changelog.md index 67218e713..c65b8929f 100644 --- a/changelog.md +++ b/changelog.md @@ -1,31 +1,22 @@ -Version 4.0.0-beta4 +Version 4.0.0-rc1 ------------- - - All callbacks now have the port as `this` - - Disconnections now always attempt to close the port, and you'll always get a `close` event after a `disconnect` event - - Removed undocumented callbacks from the options object `disconnectedCallback` and `dataCallback` - - [unix] Ports are now locked by default with the new `lock` options matches windows default behavior - - [windows] known issue `lock` false doesn't work (no change in behavior) - -Version 4.0.0-beta3 -------------- - - Contributors guide - Requiring `serialport` now returns the SerialPort constructor function instead of a factory object. `SerialPort.SerialPort` is now depreciated. - - `SerialPort` constructor now throws on argument errors. - - `openImmediately` is now part of the options object and renamed to `autoOpen` + - `SerialPort` constructor now throws on argument errors immediately. + - Removed `openImmediately` from the constructor's api, the functionality is now named `autoOpen` on the options object. + - Removed extraneous flow control settings from the `flowControl` option, use the specific options to set these flags now. + - Removed undocumented callbacks from the options object `disconnectedCallback` and `dataCallback` + - `.write(writeCallback)` now only calls it's callback once after the entire write operation, it used to be called for each write cycle and return the bytes written. This reduces the number of callbacks by hundreds of thousands over a megabyte at low bandwidth. + - All callbacks are called in the context of the port, `this` now equals the port. + - Disconnections now always attempt to close the port, and you'll always get a `close` event after a `disconnect` event + - Reanmed `serialportlist` to `serialport-list` + - Renamed `serialportterm` to `serialport-term` - [unix] `.drain` and `.set` now properly report errors + - [unix] Ports are now locked by default with the new `lock` options matches windows default behavior - [windows] `.update()` now supports windows for changing baud rates - -Version 4.0.0-beta2 -------------- - - Remove extra flow control settings - [windows] Fixed a bug where we weren't properly opening ports (provides better support virtual com ports too) thanks to @RogerHardiman - -Version 3.2.0-beta1 -------------- - - Fix bug where write callback was being called multiple times when write operations blocked - - [windows] refactored write code to be less complex - - [unix] refactored write code to be less complex - - added arduino required integration tests + - [windows] known issue `lock: false` doesn't work (no change in behavior) + - Added our first arduino required integration tests + - Added a contributors guide Version 3.1.2 ------------- diff --git a/package.json b/package.json index 8c5b99395..172411c8a 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "serialport", - "version": "4.0.0-beta4", + "version": "4.0.0-rc1", "description": "Node.js package to access serial ports. Welcome your robotic javascript overlords. Better yet, program them!", "author": { "name": "Chris Williams", @@ -10,7 +10,7 @@ "binary": { "module_name": "serialport", "module_path": "build/{configuration}/", - "host": "https://github.com/EmergingTechnologyAdvisors/node-serialport/releases/download/4.0.0-beta4" + "host": "https://github.com/EmergingTechnologyAdvisors/node-serialport/releases/download/4.0.0-rc1" }, "main": "./lib/serialport", "repository": {