Add contributing docs for making a config change
@@ -68,6 +68,36 @@ To check out this repository:
_Adding the `upstream` remote sets you up nicely for regularly [syncing your
fork](https://help.github.com/articles/syncing-a-fork/)._
+## Making a config change
+
+Some changes to the skaffold code require a change to the skaffold config. These changes require a few extra steps:
+
+* Check to see what the latest config version was at the time of the last release. The easiest way to do this is to view the skaffold source on github at the last released tag.
+
+* Check the current config version in the code. This can be found in `pkg/skaffold/schema/latest/config.go`: look for something like
+
+```golang
+const Version string = "skaffold/v1beta9"
+```
+* If the config versions are different, do nothing. Somebody has already bumped the config version for this release cycle.
+
+* **If the config versions are the same**:
+
+ * Run `./hack/new_version.sh` to freeze the current config version and cut a new version.
+
+ * Commit these generated changes, and submit a PR.
+
+Once you've done this, continue making your changes locally, including the new config change.
+**Any new config changes belong in pkg/skaffold/schema/latest/config.go. Do not edit the older config versions.**
+
+* Be sure and update the documentation in `pkg/skaffold/schema/<previous_config_version>/upgrade.go` with any additions, removals, or updates you make to the config.
+
+* In case of backwards compatibility issues, update the `Upgrade()` method from the previous config version appropriately. This is usually required when a previously existing field in the config is changed, but **not** when a new field is added.
+
+*Note: the Upgrade() method is called by skaffold automatically for older config versions. This can also be done manually by users by running `skaffold fix`.*
+
+* Finally, before committing your final changes and opening your pull request, be sure and run `make test` locally. This will regenerate the JSON schemas for the skaffold config with your new changes. Commit the resulting changes autogenerated by the scripts.
+
## Building skaffold
To build with your local changes you have two options:
