docs: add deprecation note to migration guide

Also add documentation for formations key.

docs/appendices/0.25.0-migration-guide.md

@@ -10,3 +10,4 @@
 - In previous versions of Dokku, the only way to specify a custom `Dockerfile` was to use the `docker-options` plugin to set the `--file` flag for a docker build. As of 0.25.0, the `builder-dockerfile:set` command should be used instead, as outlined in the [docs here](/docs/deployment/builders/dockerfiles.md#changingthe-dockerfile-location). Usage of the old method should be migrated to the new method.
 - The `--rm` and ``--rm-container` flags may be specified but no longer have any effect on `dokku run`.
 - The `--detach` flag is deprecated in favor of the `run:detached` command.
+- The `DOKKU_SCALE` file is deprecated. Please see the [process management documentation](/docs/processes/process-management.md#manually-managing-process-scaling) for more information on it's replacement with the `formations` key of the `app.json` file.

docs/processes/process-management.md

@@ -106,7 +106,7 @@ web:  1
 
 #### Via CLI
 
-> This functionality is disabled if the formation is managed via a file such as `DOKKU_SCALE`.
+> This functionality is disabled if the formation is managed via the `formations` key of `app.json`.
 
 Dokku can also manage scaling itself via the `ps:scale` command. This command can be used to scale multiple process types at the same time.
 
@@ -128,22 +128,30 @@ dokku ps:scale --skip-deploy node-js-app web=1
 
 #### Manually managing process scaling
 
-> Using a `DOKKU_SCALE` formation file disables the ability to use `ps:scale` for scaling.
+> Using a `formations` key in an `app.json` file disables the ability to use `ps:scale` for scaling.
 
-A `DOKKU_SCALE` file can be committed to the root of the pushed app repository, and must be within the built image artifact in the image's working directory as shown below.
+An `app.json` file can be committed to the root of the pushed app repository, and must be within the built image artifact in the image's working directory as shown below.
 
-- Buildpacks: `/app/DOKKU_SCALE`
-- Dockerfile: `WORKDIR/DOKKU_SCALE` or `/DOKKU_SCALE`
-- Docker Image: `WORKDIR/DOKKU_SCALE` or `/DOKKU_SCALE`
+- Buildpacks: `/app/app.json`
+- Dockerfile: `WORKDIR/app.json` or `/app.json` (if no working directory specified)
+- Docker Image: `WORKDIR/app.json` or `/app.json` (if no working directory specified)
 
-The `DOKKU_SCALE` file format is as follows:
+The `formations` key should be specified as follows in the `app.json` file:
 
 ```Procfile
-web=1
-worker=2
+{
+  "formations": {
+    "web": {
+      "quantity": 1
+    },
+    "worker": {
+      "quantity": 4
+    }
+  }
+}
 ```
 
-Removing the file will result in Dokku respecting the `ps:scale` command for setting scale values.
+Removing the file will result in Dokku respecting the `ps:scale` command for setting scale values. The values set via the `app.json` file from a previous deploy will be respected.
 
 #### The `web` process