Merge pull request #5332 from strapi/single-types/migration-guide

Single types migration guide and policy doc update

docs/3.0.0-beta.x/concepts/policies.md

@@ -5,26 +5,9 @@
 Policies are functions which have the ability to execute specific logic on each request before it reaches the controller's action. They are mostly used for securing business logic easily.
 Each route of the project can be associated to an array of policies. For example, you can create a policy named `isAdmin`, which obviously checks that the request is sent by an admin user, and use it for critical routes.
 
-Policies can be:
-
-- `global`: Can be used within the entire project.
-- `scoped`: Can only be used by single API or plugin.
-
 ### Where are the policies defined?
 
-The API and scoped plugin policies are defined in each `./api/**/config/policies/` folders and plugins. They are respectively exposed through `strapi.api.**.config.policies` and `strapi.plugins.**.config.policies`. The global policies are defined at `./config/policies/` and accessible via `strapi.config.policies`.
-
-### Global policies
-
-Global policies are reusable throughout the entire app.
-
-### Scoped policies
-
-A policy defined in an API or plugin is usable only from this API or plugin. You don't need any prefix to use it.
-
-### Plugin policies
-
-Plugin policies are usable from any app API.
+The policies are defined in each `./api/**/config/policies/` folders and plugins. They are respectively exposed through `strapi.api.**.config.policies` and `strapi.plugins.**.config.policies`. The global policies are defined at `./config/policies/` and accessible via `strapi.config.policies`.
 
 ## How to create a policy?
 
@@ -110,9 +93,9 @@ Plugins can add and expose policies into your app. For example, the plugin **Use
 
 The policy `isAuthenticated` located in the `users-permissions` plugin will be executed before the `find` action in the `Restaurant.js` controller.
 
-### Scoped Policies
+### Api Policies
 
-The scoped policies can only be associated to the routes defined in the API where they have been declared.
+The api policies can be associated to the routes defined in the API where they have been declared.
 
 **Path —** `./api/restaurant/config/policies/isAdmin.js`.
 
@@ -146,9 +129,26 @@ module.exports = async (ctx, next) => {
 
 The policy `isAdmin` located in `./api/restaurant/config/policies/isAdmin.js` will be executed before the `find` action in the `Restaurant.js` controller.
 
-::: tip
-The policy `isAdmin` can only be applied to the routes defined in the `/api/restaurant` folder.
-:::
+### Using a policy outside it's api
+
+To use a policy in another api you can reference it with the following syntax: `{apiName}.{policyName}`.
+
+**Path —** `./api/category/config/routes.json`.
+
+```json
+{
+  "routes": [
+    {
+      "method": "GET",
+      "path": "/categories",
+      "handler": "Category.find",
+      "config": {
+        "policies": ["restaurant.isAdmin"]
+      }
+    }
+  ]
+}
+```
 
 ## Advanced usage
 

docs/3.0.0-beta.x/migration-guide/README.md

@@ -9,6 +9,7 @@ Read the [Migration guide from alpha.26 to beta](migration-guide-alpha.26-to-bet
 - [Migration guide from beta.15 to beta.16](migration-guide-beta.15-to-beta.16.md)
 - [Migration guide from beta.16+ to beta.17.4](migration-guide-beta.16-to-beta.17.4.md)
 - [Migration guide from beta.17+ to beta.18](migration-guide-beta.17-to-beta.18.md)
+- [Migration guide from beta.18 to beta.19](migration-guide-beta.18-to-beta.19.md)
 
 ## Alpha guides
 

docs/3.0.0-beta.x/migration-guide/migration-guide-beta.18-to-beta.19.md

@@ -0,0 +1,55 @@
+# Migration guide from beta.18.x to beta.19
+
+Upgrading your Strapi application to `v3.0.0-beta.19`.
+
+**Make sure your server is not running until then end of the migration**
+
+## Upgrading your dependencies
+
+Start by upgrading your dependencies. Make sure to use exact versions.
+
+Update your package.json accordingly:
+
+```json
+{
+  //...
+  "dependencies": {
+    "strapi": "3.0.0-beta.19",
+    "strapi-admin": "3.0.0-beta.19",
+    "strapi-connector-bookshelf": "3.0.0-beta.19",
+    "strapi-plugin-content-manager": "3.0.0-beta.19",
+    "strapi-plugin-content-type-builder": "3.0.0-beta.19",
+    "strapi-plugin-email": "3.0.0-beta.19",
+    "strapi-plugin-graphql": "3.0.0-beta.19",
+    "strapi-plugin-upload": "3.0.0-beta.19",
+    "strapi-plugin-users-permissions": "3.0.0-beta.19",
+    "strapi-utils": "3.0.0-beta.19"
+  }
+}
+```
+
+Then run either `yarn install` or `npm install`.
+
+## Policies syntax change
+
+We decided to change the policies naming convention to match with the future naming convetion we will be using throughout the project.
+
+**Before**
+
+- Global policy: `global.{policy}`.
+- Plugin policy: `plugins.{pluginName}.{policy}`.
+
+**After**
+
+- Global policy: `global::{policy}`.
+- Plugin policy: `plugins::{pluginName}.{policy}`.
+
+We are also introductin application naming so you can access an api policy easily or reference it absolutely when the context doesn't allow forto find out directly.
+
+You can now reference a policy located at `./api/{apiName}/config/policies/{policy}` with the following syntax: `{apiName}.{policy}`.
+
+Although we do not recommend it (error prone), you can still access a local policy with the syntax `{policy}` . This syntax will only allow access to a policy declared in the api you are referencing it from. (e.g, polici in `restaurant` api and route in `restaurant` api only).
+
+## Rebuilding your administration panel
+
+Now delete the `.cache` and `build` folders. Then run `yarn develop`.

docs/3.0.0-beta.x/plugin-development/backend-development.md

@@ -77,7 +77,7 @@ A plugin can also use a globally exposed policy in the current Strapi project.
       "path": "/",
       "handler": "MyPlugin.index",
       "config": {
-        "policies": ["global.isAuthenticated"]
+        "policies": ["global::isAuthenticated"]
       }
     }
   ]
@@ -96,7 +96,7 @@ A plugin can have its own policies, such as adding security rules. For instance,
       "path": "/",
       "handler": "MyPlugin.index",
       "config": {
-        "policies": ["plugins.myPlugin.isAuthenticated"]
+        "policies": ["plugins::myplugin.isAuthenticated"]
       }
     }
   ]

examples/getstarted/api/address/controllers/Address.js

@@ -5,4 +5,4 @@
  * to customize this controller
  */
 
-module.exports = {};
+module.exports = { test() {} };