Merge pull request #617 from buildpacks/update-migration

Clarify and expand on implications of upgrading to Platform API 0.10

content/docs/reference/spec/migration/buildpack-api-0.8-0.9.md

@@ -22,7 +22,7 @@ Hand-in-hand with shell removal is the introduction of overridable process argum
 
 In `launch.toml`, `command` is now a list. The first element in `command` is the command, and all following entries are arguments that are always provided to the process, regardless of how the application is started. The `args` list now designates arguments that can be overridden by the end user - if supported by the platform (Platform API version 0.10 and above). For further details, see the platform [migration guide](/docs/reference/spec/migration/platform-api-0.9-0.10).
 
-For older platforms (Platform API version 0.9 and below), arguments in `args` will be appended to arguments in `command`, negating the new functionality (but preserving compatibility).
+For older platforms (Platform API version 0.9 and below), arguments in `command` will be prepended to arguments in `args`, negating the new functionality (but preserving compatibility).
 
 ### Image extensions are supported (experimental)
 

content/docs/reference/spec/migration/platform-api-0.9-0.10.md

@@ -38,6 +38,18 @@ docker run --entrypoint from-newer-buildpack my-image user-1 user-2
 
 will result in the following command invocation: `some-command always-1 always-2 user-1 user-2`.
 
+#### Implications of upgrading
+
+For processes from newer buildpacks, upgrading the platform (without changing anything else) will change the command invocation for end-users.
+
+As an example, the following on Platform API version 0.9:
+
+```
+docker run --entrypoint from-newer-buildpack my-image user-1 user-2
+```
+
+will result in the following command invocation: `some-command always-1 always-2 override-1 override-2 user-1 user-2`, where overridable arguments are treated like regular arguments, and user-provided arguments are always appended. Upgrading the platform will cause `override-1` and `override-2` to be dropped, as shown above.
+
 #### Older buildpacks
 
 Process types contributed by older buildpacks (Buildpack API 0.8 and below) do not have overridable process arguments. Looking at metadata.toml:
@@ -51,7 +63,7 @@ args = ["always-1", "always-2"]
 The `command` list will never have more than one element. `always-1` and `always-2` are arguments that are always provided to `some-command`. If no user-provided arguments are specified when the application image is launched, `always-1` and `always-2` will be provided only. If user-provided arguments are specified, these will be **appended** to the `args` list. Example:
 
 ```
-docker run --entrypoint from-newer-buildpack my-image
+docker run --entrypoint from-older-buildpack my-image
 ```
 
 will result in the following command invocation: `some-command always-1 always-2`. However:
@@ -62,6 +74,10 @@ docker run --entrypoint from-older-buildpack my-image user-1 user-2
 
 will result in the following command invocation: `some-command always-1 always-2 user-1 user-2`.
 
+#### Implications of upgrading
+
+For processes from older buildpacks, upgrading the platform will not change the command invocation.
+
 ### Image extensions are supported (experimental)
 
 Platform 0.10 introduces image extensions as experimental components for customizing build and run-time base images (see [here](/docs/features/dockerfiles) for more information). Image extensions output Dockerfiles which are applied by the lifecycle using [kaniko][https://github.com/GoogleContainerTools/kaniko], a tool for building container images in Kubernetes, as a library.