Merge pull request #2823 from strongloop/docs/remove-release-notes
Remove 3.0 DEVELOPING & RELEASE-NOTES
This commit is contained in:
Miroslav Bajtoš
GitHub
commit
31913c048d
|
|
@ -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.
|
|
||||||
|
|
@ -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).
|
|
||||||
Loading…
Reference in New Issue