[YUNIKORN-2610] Announce deprecation of YuniKorn plugin mode (apache#427

)

Closes: apache#427

docs/user_guide/deployment_modes.md

@@ -24,28 +24,46 @@ under the License.
 
 ## YuniKorn deployment modes
 
-YuniKorn can be deployed in two different modes: standard and plugin. In standard mode, YuniKorn runs as a customized
-Kubernetes scheduler. In plugin mode, YuniKorn is implemented as a set of plugins on top of the default Kubernetes
-scheduling framework.
+***NOTE:*** **This section is maintained largely for historical context.
+The plugin deployment mode is deprecated and no longer supported. The
+removal timeline agreed upon by the YuniKorn community is as follows:**
 
-In both cases, it is recommended to run the admission controller as well, as this will ensure that only a single
-scheduler is active within your Kubernetes cluster. In this mode, the default Kubernetes scheduler (which is always running)
-will be bypassed for all pods except YuniKorn itself.
+* **YuniKorn 1.6**: Deprecation announced
+* **YuniKorn 1.7**: Scheduler will emit warnings if plugin mode is in use
+* **YuniKorn 1.8**: YuniKorn will no longer ship plugin mode binaries
+* **YuniKorn 1.9**: Implementation removed from codebase
 
-## Which version should I use?
+YuniKorn can be deployed in two different modes: standard and plugin.
+In standard mode, YuniKorn runs as a standalone Kubernetes scheduler.
+In plugin mode (now deprecated), YuniKorn is implemented as a set of
+plugins on top of the default Kubernetes scheduling framework.
+
+Regardless of the YuniKorn deployment mode in use, it is recommended to
+run the admission controller as well, as this will ensure that only a single
+scheduler is active within your Kubernetes cluster. In this mode, the default
+Kubernetes scheduler (which is always running) will be bypassed for all pods
+except YuniKorn itself.
 
 ### Standard mode
 
-Standard mode is currently the default. It is stable, efficient, and very performant. It is well-suited for
-deployments where most if not all pods are leveraging the queueing features of YuniKorn.
+Standard mode is currently the default. It is stable, efficient, and very
+performant. It is well-suited for all YuniKorn deployments and is recommended.
 
 ### Plugin mode
 
-Plugin mode is a new deployment model where the scheduler is implemented on top of the default Kubernetes scheduling
-logic, allowing for better compatibility with the default Kubernetes scheduler. It is well-suited for mixed
-workloads (traditional Kubernetes as well as queued applications).
-
-Plugin mode is currently very new and has therefore not yet reached the maturity level of standard mode.
+**Deprecated for removal**
 
-To activate plugin mode when deploying with Helm, set the variable `enableSchedulerPlugin` to `true`.
+Plugin mode was an experimental deployment model where the scheduler was
+implemented on top of the default Kubernetes scheduler as a set of plugins.
+Originally, this was expected to help provide better compatibility with the
+default Kubernetes scheduler, but that did not end up being the case.
+Consequently, the plugin mode is now deprecated and will be removed from a
+future YuniKorn release.
 
+It is not recommended to use plugin mode for any new deployments, and existing
+users should migrate to standard mode as soon as practically possible. The
+standard mode is much more mature, providing excellent compatibility with the
+default Kubernetes scheduler (as it now uses the same scheduler plugins
+internally) while providing significantly better performance then either the
+default Kubernetes scheduler or the now deprecated YuniKorn plugin deployment
+mode.