From a03bc328a9fadab9779b1df63b7b0d0f9219ff9b Mon Sep 17 00:00:00 2001
From: Shane Utt <shaneutt@linux.com>
Date: Tue, 10 Sep 2019 14:02:18 -0400
Subject: [PATCH] Update README.md and CONTRIBUTING.md

---
 CONTRIBUTING.md | 44 ++++++++++++++++++++++++++++++++++++++++++++
 README.md       | 16 ++++++++++++++++
 2 files changed, 60 insertions(+)
 create mode 100644 CONTRIBUTING.md

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
new file mode 100644
index 0000000..1d459b0
--- /dev/null
+++ b/CONTRIBUTING.md
@@ -0,0 +1,44 @@
+# Contributing
+
+Kubeaddons-Configs is an Addon Repository which manages a predefined set of Addons and their configurations for deployment via [Kubeaddons](https://github.com/mesosphere/kubeaddons).
+
+The [Kubeaddons Contributing Documentation](https://github.com/mesosphere/kubeaddons/blob/master/CONTRIBUTING.md) governs contributions to this repo in addition to other sections of this document.
+
+## PR Readiness
+
+PR's should be marked `wip` until the following are taken care of:
+
+1. Manual testing of the Addon has succeeded against the most recent release of the `kubeaddons` controller
+2. CI must pass
+
+Once these are complete the PR can be marked as `ready`.
+
+## Creating New Addons
+
+You can create new Addons by providing an `Addon` [resource](https://kubernetes.io/docs/concepts/) in a [manifest](https://kubernetes.io/docs/concepts/cluster-administration/manage-deployment/) placed in the `templates/` directory.
+
+See the [Custom Resource Definition](https://github.com/mesosphere/kubeaddons/blob/master/config/crd/bases/kubeaddons.mesosphere.io_addons.yaml) for the `Addon` type for structure, and the [samples](https://github.com/mesosphere/kubeaddons/tree/master/config/samples) for more explicit implementation examples.
+
+The overall workflow for contributing a new Addon is:
+
+1. define an `Addon` resource as discussed above
+2. install the [Kubeaddons Controller](https://github.com/mesosphere/kubeaddons/blob/master/config/samples/manager.yaml) to your Kubernetes cluster
+3. deploy the new `Addon`
+4. watch the pod logs for the controller, and ensure that the `Addon` status becomes `ready: true`
+5. test the addon functionality as appropriate for its type
+
+1. Manual testing of the Addon has succeeded against the most recent release of the `kubeaddons` controller
+2. CI must pass
+
+## Customizing Existing Addons
+
+Addons can be customized via their manifests in the `templates/` directory.
+
+Changing an addons name or namespace is done in the `metadata` field.
+
+Configuration of the `Addon` resource itself is primarily done via via the `spec` field, particularly changing the [helm values configuration](https://v3.helm.sh/docs/topics/chart_best_practices/values/) of a helm-based addon is done via the `spec.ChartReference.Values` field.
+
+## ExtraSteps
+
+Some addons may be in need of additional logic beyond what's available in the implementing driver (e.g. Helm). For instance: it may be desired to have an addo generate a password for a user interface on startup and store that in a [Kubernetes Secret](https://kubernetes.io/docs/concepts/configuration/secret/). These kinds of tasks can be accomplished by adding functionality to the [Kubeaddons Extrasteps](https://github.com/mesosphere/kubeaddons-extrasteps) repo which packages tooling into [initContainers](https://kubernetes.io/docs/concepts/workloads/pods/init-containers/) and [jobs](https://kubernetes.io/docs/concepts/workloads/controllers/jobs-run-to-completion/) for after-deployment Addon logic.
+
diff --git a/README.md b/README.md
index 5c52a9b..427bc64 100644
--- a/README.md
+++ b/README.md
@@ -1,3 +1,19 @@
 # Addon Repository
 
 This is a repository for `Addon` resources managed by `Kubeaddons`.
+
+# Contributing
+
+See our [contributing documentation](/CONTRIBUTING.md) for details on how to contribute to this repo.
+
+## Goals
+
+* provides a repository for storing addon resources with default configurations
+* provides alternative configurations for addons for specific cloud providers
+
+## Non-Goals
+
+Logic for addon configurations doesn't belong in these configurations, nor should changes here cover the scope of adding or managing additional resources for an addon (resources can be added via [charts](https://github.com/mesosphere/charts)).
+
+If optional [initContainer](https://kubernetes.io/docs/concepts/workloads/pods/init-containers/) or [job](https://kubernetes.io/docs/concepts/workloads/controllers/jobs-run-to-completion/) functionality is needed for an addon you're working on you may want to use [kubeaddons extrasteps](https://github.com/mesosphere/kubeaddons-extrasteps) to add your custom logic and build a docker image for use here. It may be more appropriate to add these containers to [Charts](https://github.com/mesosphere/charts) however if they're absolutely required for the application's function.
+