diff --git a/3.0-DEVELOPING.md b/3.0-DEVELOPING.md deleted file mode 100644 index 7ab6762e..00000000 --- a/3.0-DEVELOPING.md +++ /dev/null @@ -1,38 +0,0 @@ -# How to develop LoopBack 3.0 - -## Keeping track of major and breaking changes - -We will need a detailed release notes for 3.0. To make our life easier, we -should build them incrementally in a file called `3.0-RELEASE-NOTES.md`. -Each pull request containing a major change must include an update -of this file describing the change for a user upgrading from 2.x to 3.0. - -## Branch setup - -Most patches should be landed on the master branch, the new 3.0 release -will be eventually released from master too. - -It is up to the discretion of reviewers to decide which changes to -back-port from master to 2.x. Initially, we should probably land all bug fixes -and most backwards-compatible enhancements. This rule should be revisited -once 3.0.0 was released. - -## Publishing pre-release versions - -To make it easy for LB developers to test out the upcoming 3.0 version, we -should regularly publish pre-release versions to npmjs. However, extra care -must be taken to ensure "npm install" keeps downloading the current 2.x series. - -When 2.x branch was created, we have changed package.json on the *master* -branch and - - 1. changed the version string to `"3.0.0-alpha.1"` - 2. added the following bit: `"publishConfig": { "tag": "next" }` - -Whenever making a new pre-release version, increment the latest number: -`3.0.0-alpha.2`, `3.0.0-alpha.3`, etc. Once get closer to the release date, -we can release `3.0.0-beta.1`, possibly also `3.0.0-rc.1`. - -The benefit of this version scheme is that module consumers can use carrot -operator to get automatic updates: `"^3.0.0-alpha.1"` matches all versions -from the previous paragraph. diff --git a/3.0-RELEASE-NOTES.md b/3.0-RELEASE-NOTES.md deleted file mode 100644 index 8f48e62a..00000000 --- a/3.0-RELEASE-NOTES.md +++ /dev/null @@ -1,234 +0,0 @@ -# List of notable changes made between 2.x and 3.0 - -All breaking changes must be described here. When adding a new entry, -always describe the impact on users and instructions for upgrading -applications from 2.x to 3.0. - -## loopback-datasource-juggler was moved from peerDependencies to dependencies - -Originally, we (ab)used peer dependencies to ensure there is only one instance -of loopback-datasource-juggler in the dependency tree, so that there is only -one singleton instance of model registry. This was very fragile and might not -have worked in certain edge cases. - -We have reworked loopback-datasource-juggler and connectors to not rely on -a single juggler instance anymore. As the last step, juggler became a regular -dependency. - -https://github.com/strongloop/loopback/issues/275 - -When upgrading application from previous loopback versions, simply remove -loopback-datasource-juggler from your dependencies. - -## always use bluebird as promise library - -In version 3.0, we always use bluebird as our promise library -instead of `global.Promise`. -We consider Bluebird API as part of LoopBack API from now on, -you are welcome to use any Bluebird-specific methods in your applications. - -If you are using LoopBack with a custom promise implementation provided -via `global.Promise`, -you will have to check all places where you are using non-standard promise API -and update them to use Bluebird API instead. - -Please see [related code changes](https://github.com/strongloop/loopback/pull/1896). - -## new method of defining remoting metadata - -In 2.0, remote methods were defined as: -``` -methods: { - staticMethod: { - isStatic: true, - http: { path: '/static' } - }, - instanceMethod: { - isStatic: false, - http: { path: '/instance' } - } -} -``` - -For 3.0, the isStatic flag is no longer required and will be determined from the method name. -Method name starting with "prototype." will be the same as having isStatic flag set to false. -``` -methods: { - staticMethod: { - http: { path: '/static' } - }, - 'prototype.instanceMethod': { - http: { path: '/instance' } -} -``` - -Please see [related code changes](https://github.com/strongloop/loopback/pull/2174). - -## remove `Change.handleError` -`Change.handleError` is now removed as it was used inconsistenly for a subset of possible -errors only. All Change methods will report all errors to the caller via the callback. - -Use PersistedModel to report change-tracking errors via the existing method -PersistedModel.handleChangeError. This method can be customized on a per-model basis to -provide different error handling. - -Please see [related code changes](https://github.com/strongloop/loopback/pull/2308). - - -## remove unused user properties -The following properties are removed from the built-in User model in 3.0: -- credentials -- challenges -- status -- created -- lastUpdated - -Developers that are relying on these properties, can redefine them in `user.json` or equivalent model.json as follow: -```json -{ - "name": "MyUser", - "base": "User", - "properties": { - "credentials": { "type": "object" }, - "challenges": { "type": "object" }, - "status": "string", - "created": "date", - "lastUpdated": "date" - } -} -``` - -Please see [related code changes](https://github.com/strongloop/loopback/pull/2299). - -## Remove getters for Express 3.x middleware - -Express 4.x stopped bundling commonly-used middleware. To simplify migration -of LoopBack 1.x applications (powered by Express 3.x) to LoopBack 2.x (powered -by Express 4.x), we created getter properties to allow developers to keep using -the old convention. - -We have removed these getters in LoopBack 3.0, here is the full list of -removed properties together with the middleware module name to use instead: - - - `loopback.compress` - use `require('compression')` instead - - `loopback.timeout` - use `require('connect-timeout')` instead - - `loopback.cookieParser` - use `require('cookie-parser')` instead - - `loopback.cookieSession` - use `require('cookie-session')` instead - - `loopback.csrf` - use `require('csurf')` instead - - `loopback.errorHandler` - use `require('errorhandler')` instead - - `loopback.session` - use `require('express-session')` instead - - `loopback.methodOverride` - use `require('method-override')` instead - - `loopback.logger` - use `require('morgan')` instead - - `loopback.responseTime` - use `require('response-time')` instead - - `loopback.favicon` - use `require('serve-favicon')` instead - - `loopback.directory` - use `require('serve-index')` instead - - `loopback.vhost` - use `require('vhost')` instead - -We have also removed `loopback.mime`, which was always set to `undefined`. - -See [loopback#2349](https://github.com/strongloop/loopback/pull/2394). - -## Remove `loopback#errorhandler` - -We have removed `loopback#errorhandler` middleware, users should use `strong-error-handler` directly. - -```js -// server/middleware.json -{ - // ... - "final:after": { - "strong-error-handler": {} - } -} - -// server/middleware.development.json -{ - "final:after": { - "strong-error-handler": { - "params": { - "debug": true - } - } -} -``` - -See also strong-error-handler's [options](https://github.com/strongloop/strong-error-handler#options) and the [related code change](https://github.com/strongloop/loopback/pull/2411). - -## Remove current context API and middleware - -We have removed the following current-context-related APIs: - - - `loopback.getCurrentContext` - - `loopback.createContext` - - `loopback.runInContext` - -Additionally, `loopback#context` middleware and `remoting.context` server -config were removed too. - -#### Upgrading from 2.x to 3.x - -When upgrading from LoopBack 2.x, you need to disable or remove -`remoting.context` configuration in your server config. - -```js -{ - "remoting": { - "context": false, // or remove completely - // etc. - }, - // etc. -} -``` - -Without this change, you will see the following error on the first HTTP request -received: - -``` -Unhandled error for request GET /api/Users: -Error: remoting.context option was removed in version 3.0. -See https://docs.strongloop.com/display/APIC/Using%20current%20context for more -details. - at restApiHandler (.../node_modules/loopback/server/middleware/rest.js:44:15) - at Layer.handle [as handle_request] (.../node_modules/express/lib/router/layer.js:95:5) -``` - -#### Setting up "current context" in 3.x - -To setup "current context" feature in your LoopBack 3.x application, you -should use [loopback-context](https://www.npmjs.com/package/loopback-context) -module: - - 1. Add `loopback-context` to your dependencies - - 2. Configure the new context middleware in your `server/middleware-config.json` file - ```json - { - "initial": { - "loopback-context#per-request": {} - } - } - ``` - - 3. Replace all usages of `loopback.getCurrentContext` with the following: - ```js - // at the top of your file - var LoopBackContext = require('loopback-context'); - - // in your code - var ctx = LoopBackContext.getCurrentContext(); - if (ctx) { - // use the context - } - ``` - -See also [loopback#2564](https://github.com/strongloop/loopback/pull/2564) -and the official [documentation](https://docs.strongloop.com/display/APIC/Using+current+context) - -## Remove sugar for creating models - -`app.model(modelName, settings)`, a sugar for creating non-existing model, is -now removed in favor of promoting use of: -- `app.registry.createModel(modelName, properties, options)` to create new model -- `app.model(modelCtor, config)` to update existing model and attach it to app - -Please see [related code changes](https://github.com/strongloop/loopback/pull/2401).