diff --git a/docs/public/breaking-changes-in-odo-2.2.adoc b/docs/public/breaking-changes-in-odo-2.2.adoc
new file mode 100644
index 00000000000..3cb94310e07
--- /dev/null
+++ b/docs/public/breaking-changes-in-odo-2.2.adoc
@@ -0,0 +1,72 @@
+== Breaking changes in odo 2.2
+
+This document outlines the breaking changes that were introduced in odo 2.2.
+With the increased adoptation of https://devfile.github.io/[Devfiles] we have started to reduce odo's dependency on S2I[Source-to-Image]. Now if you dont know what that is then this document is not as relevant for you.
+
+As part of that effort the primary change that has happened is 
+
+* *`odo create --s2i <component-type>` would create a converted Devfile based component on the S2I images of that component type.*
+
+[source,sh]
+----
+odo create --s2i nodejs
+----
+
+Output - 
+
+[source,sh]
+----
+odo create nodejs --s2i
+Validation
+ ✓  Validating component [424ms]
+Conversion
+ ✓  Successfully generated devfile.yaml and env.yaml for provided S2I component
+
+Please use `odo push` command to create the component with source deployed
+----
+
+would generate a `devfile.yaml` which would be using the S2I images and variables that are part of the `nodejs`.
+
+* Note - This wouldn't break any existing S2I components, you are encouraged to convert then using `odo utils convert-to-devfile`. But they would still work.*
+
+* *Currently devfile components do not support `--git` and `--binary` components hence we still use S2I component flow when a user wants to create them.*
+
+[source,sh]
+----
+odo create java --s2i --git ./build.war
+Validation
+ ✓  Validating component [431ms]
+
+Please use `odo push` command to create the component with source deployed
+----
+Note - observe there wasn't any conversion step involved here.
+
+* *`odo env set DebugPort` wont work with converted devfile components, instead you would need to use `odo config set --env DEBUG_PORT`.*
+
+. Currently the `wildfly` and `dotnet` component types are not working when converted. We have an issue open for this - https://github.com/openshift/odo/issues/4623 
+
+=== Known bugs and limitations
+
+* https://github.com/openshift/odo/issues/4623
+* https://github.com/openshift/odo/issues/4615
+* https://github.com/openshift/odo/issues/4594
+* https://github.com/openshift/odo/issues/4593
+
+
+=== Frequently asked questions
+
+* Why does odo fail create to URL using `odo url create` for a component created using `odo create --s2i` even though `odo url craete` is allowed for devfile?
+
+It won’t fail in the sense that if you tried the conventional s2i approach and try to create `odo url create` it would fail with url for 8080 port already present as there would already be one for you. issue - #4621
+
+* Not sure to understand the status of the debug
+
+odo env set DebugPort wont work, instead you would need to use odo config set --env DEBUG_PORT - this is because the s2i to devfile converted devfiles dont have a debug type command defined in them. We would fix this too.
+
+* So every component will now be reported as devfile component but what about existing S2I components
+
+They should work as is mostly because we tried them and they work, maybe try `odo list` because it is quite complex to make things work across the board.
+
+* If oc based checks in tests are not going to work, is there an alternative odo support around it ?
+
+It wouldn't be right to say that you cannot use `oc` based checks, but they would break because now the s2i components are being converted to devfile, odo would generate a Kubernetes `Deployment` but the `oc` would try to find a `DeploymentConfig` on the cluster.
\ No newline at end of file