Add an API change section

Author: soltysh

HACKING.md

@@ -292,6 +292,42 @@ any local interaction with the filesystem or Docker.
 More information about running extended tests can be found in
 [test/extended/README](https://github.com/openshift/origin/blob/master/test/extended/README.md).
 
+## Changing API
+
+OpenShift is split into three major repositories:
+
+1. https://github.com/openshift/api/ - which holds all the external API objects definitions.
+1. https://github.com/openshift/client-go/ - which holds all the client code (written in Go).
+1. https://github.com/openshift/origin/ - which holds the actual code behind OpenShift.
+
+This split requires additional effort to introduce any API change.  The following steps
+should guide you through the process.
+
+1. The first place to introduce the changes is [openshift/api](https://github.com/openshift/api/).
+Here, you put your external API updates and when you are done run `make generate`.  If you
+need to introduce a new dependency run `make update-deps`, and almost never update `glide.yaml`
+directly.  When you're done open a PR against the aforementioned repository and ping
+[@openshift/api-review](https://github.com/orgs/openshift/teams/api-review) for a review.
+
+2. The next step includes updating the [openshit/client-go](https://github.com/openshift/client-go/)
+with the changes from step 1, since it vendors it.  To do so run `make update-deps` to pick up
+the changes from step 1 and then run `make generate` to update the client code with necessary
+changes.  When you're done open a PR against the aforementioned repository and ping
+[@openshift/sig-master](https://github.com/orgs/openshift/teams/sig-master) for a review.
+
+3. The final step happens in [openshift/origin](https://github.com/openshift/origin/) repository.
+As previously, run `make update-deps` to pick up the changes from previous two steps.  Afterwards
+run `make update` to generated the remaining bits in origin repository. When you're done open
+a PR against the aforementioned repository and ping [@openshift/sig-master](https://github.com/orgs/openshift/teams/sig-master)
+for a review.
+
+If at any point you have doubts about any step of the flow reach out to
+[@openshift/sig-master](https://github.com/orgs/openshift/teams/sig-master) team for help.
+
+NOTE: It may happen that during `make update-deps` step you will pick up the changes introduced
+by someone else in his PR.  In that case sync with the other PR's author and include his changes
+in your PR noting the fact to your reviewer.
+
 ## Installing Godep
 
 OpenShift and Kubernetes use [Godep](https://github.com/tools/godep) for