flesh out READMEs and contributing docs

CONTRIBUTING.md

@@ -6,11 +6,49 @@ _As contributors and maintainers of this project, and in the interest of fosteri
 
 ## Getting Started
 
-We have full documentation on how to get started contributing here:
+### Repo layout
+
+```
+├── publishers # Home for all functions metadata
+│   ├── kustomize
+│   │   ├── functions
+│   │   │   ├── fn-foo.yaml
+│   │   │   ├── fn-bar.yaml
+│   │   │   └── README.md
+│   │   ├── catalogs
+│   │   │   ├── v20220225.yaml
+│   │   │   ├── v20220101.yaml
+│   │   │   └── README.md
+│   │   └── OWNERS # OWNERS of the publisher
+│   ├── kubeflow
+│   ├── sig-cli
+│   └── OWNERS # OWNERS to approve new publishers
+├── krm-functions # Home for in-tree functions source code
+│   ├── Makefile
+│   ├── kustomize
+│   │   ├── fn-foo
+│   │   ├── README.md
+│   │   └── OWNERS # OWNERS to approve code change to the function
+│   └── sig-cli
+├── site 
+├── Makefile
+└── OWNERS
+```
+
+## Contributing in-tree KRM function source code
+
+To contribute KRM function source code, so that it can be managed and released by this repo, follow the instructions
+in the [krm-functions directory]((https://github.com/kubernetes-sigs/krm-functions-registry/tree/main/krm-functions))
+
+
+## Publishing KRM function metadata in-tree and out-of-tree functions
 
-<!---
-If your repo has certain guidelines for contribution, put them here ahead of the general k8s resources
--->
+To publish KRM function metadata, independently of where the source code lives, follow the instructions 
+in the [publishers directory](https://github.com/kubernetes-sigs/krm-functions-registry/tree/main/publishers).
+
+## General Kubernetes Contributing docs
+
+We have full documentation on how to get started contributing here:
 
 - [Contributor License Agreement](https://git.k8s.io/community/CLA.md) Kubernetes projects require that you sign a Contributor License Agreement (CLA) before we can accept your pull requests
 - [Kubernetes Contributor Guide](https://git.k8s.io/community/contributors/guide) - Main contributor documentation, or you can just jump directly to the [contributing section](https://git.k8s.io/community/contributors/guide#contributing)
@@ -20,16 +58,7 @@ If your repo has certain guidelines for contribution, put them here ahead of the
 
 - [Mentoring Initiatives](https://git.k8s.io/community/mentoring) - We have a diverse set of mentorship programs available that are always looking for volunteers!
 
-<!---
-Custom Information - if you're copying this template for the first time you can add custom content here, for example:
+[Catalog KEP]: https://github.com/kubernetes/enhancements/tree/master/keps/sig-cli/2906-kustomize-function-catalog#function-metadata-schema
 
 ## Contact Information
-
-- [Slack channel](https://kubernetes.slack.com/messages/kubernetes-users) - Replace `kubernetes-users` with your slack channel string, this will send users directly to your channel. 
-- [Mailing list](URL)
-
--->
-
-<!---
-TODO: Add a user guide doc for how to contribute in-tree and out-of-tree functions.
--->
+- [Slack channel](https://kubernetes.slack.com/messages/sig-cli-krm-functions)

OWNERS

@@ -2,3 +2,4 @@
 
 approvers:
   - krm-functions-registry-owners
+  - krm-functions-registry-maintainers

OWNERS_ALIASES

@@ -6,6 +6,9 @@ aliases:
     - KnVerey
     - mengqiy
 
+  krm-functions-registry-maintainers:
+    - natasha41575
+
   sig-cli-functions-approvers:
     - jeremyrickard
     - KnVerey

README.md

@@ -1,6 +1,17 @@
 # krm-functions-registry
 
-Public registry for KRM functions
+Public registry of KRM functions. This repo hosts a centralized index for KRM 
+functions and donated source code for some KRM functions.
+
+## Background, contributing, and releasing
+
+[KEP]
+
+[Open an Issue]
+
+[Contributor Guide]
+
+[Release Process]
 
 ## Community, discussion, contribution, and support
 
@@ -15,5 +26,10 @@ You can reach the maintainers of this project at:
 
 Participation in the Kubernetes community is governed by the [Kubernetes Code of Conduct](code-of-conduct.md).
 
+[KEP]: https://github.com/kubernetes/enhancements/tree/master/keps/sig-cli/2985-public-krm-functions-registry
+[Contributor Guide]: CONTRIBUTING.md
+[Release Process]: RELEASING.md
+[Open an Issue]: https://github.com/kubernetes-sigs/krm-functions-registry/issues
+
 [owners]: https://git.k8s.io/community/contributors/guide/owners.md
 [Creative Commons 4.0]: https://git.k8s.io/website/LICENSE

RELEASING.md

@@ -0,0 +1,5 @@
+# Release Process \[TODO\]
+
+This doc will cover the release process for the in-tree KRM
+functions whose source code is stored here.
+

krm-functions/README.md

@@ -0,0 +1,35 @@
+# KRM Functions
+
+This directory is the home for the source code for all in-tree functions that are maintained and
+released by this repository. 
+
+## Requirements
+
+By donating a function's source code to this repo, you are donating the function to SIG-CLI. We cannot
+accept 3rd party functions as in-tree functions.
+
+## Files
+
+Each publisher will need to create their own subdirectory `krm-functions/{PUBLISHER}/` 
+in this directory to store their functions source code, under . For example, SIG-CLI sponsored functions are located
+under `krm-functions/sig-cli/`.
+
+Each function must be in its own subdirectory `krm-functions/{PUBLISHER}/{FUNCTION NAME}/`. This directory should 
+contain: 
+- An OWNERS file to approve code changes to the function.
+- A README.md file to provide a user guide for the function.
+- Source code and unit tests.
+- A Dockerfile that describes how to build the function image.
+- An `examples/` directory. An `examples/` directory. Examples that will serve both as examples for functions and as e2e tests. Each example should have its
+  own subdirectory `krm-functions/{PUBLISHER}/{FUNCTION NAME}/examples/{EXAMPLE_NAME}/`, and this directory should contain:
+  - A README.md file that serves as a guide for the example.
+  - A subdirectory `.expected`. This should contain two files:
+    - `exec.sh`: A script that will run your example. This script will be run on the example directory it is in. This can
+      be something as simple as `kustomize build --enable-alpha-plugins > resources.yaml`.
+    - `diff.patch`: This file should contain the expected diff between the original example directory files and the files 
+      after `exec.sh` is run.
+  - Any additional files needed for your examples to run. For example, if you are running `kustomize build` in your `exec.sh`
+    script, you will need a kustomization file. 
+
+An example of this is SIG-CLI's [render-helm-chart](https://github.com/kubernetes-sigs/krm-functions-registry/tree/main/krm-functions/sig-cli/render-helm-chart) 
+function.

krm-functions/sig-cli/render-helm-chart/README.md

@@ -19,8 +19,6 @@ helm binary directly.
 You can learn more about helm [here][helm] and more about helm
 charts [here][charts].
 
-<!--mdtogo:Long-->
-
 ## Usage
 
 This function can be used with any KRM function orchestrators such to render a specified helm chart.
@@ -29,8 +27,6 @@ field is needed for local charts.
 
 ### FunctionConfig
 
-<!--mdtogo:Long-->
-
 There are 2 kinds of `functionConfig` supported by this function:
 
 - `ConfigMap`
@@ -96,7 +92,6 @@ helmCharts:
       valuesFiles: []string
       valuesInline: map[string]interface{}
       valuesMerge: string
-
 ```
 
 | Field           |  Description | Example
@@ -110,6 +105,7 @@ helmCharts:
 `name`            | The name of the chart | minecraft
 `version`         | The version of the chart | 3.1.3
 `repo`            | A URL locating the chart on the internet | https://itzg.github.io/minecraft-server-charts
+`apiVersions`     | Kubernetes api versions used for Capabilities.APIVersions | acme.cert-manager.io/v1
 `releaseName`     | Replaces RELEASE_NAME in the chart template output | test
 `namespace`       | Sets the target namespace for a release (`.Release.Namespace` in the template) | my-namespace
 `nameTemplate`    | Specify the template used to name the release | gatekeeper
@@ -120,8 +116,6 @@ helmCharts:
 `valuesFiles`     | Remote or local filepaths to use instead of the default values that accompanied the chart. The default values are in '{chartHome}/{name}/values.yaml', where `chartHome` and `name` are the parameters defined above. | Using a local values file: path/to/your/values.yaml <br> <br> Using a remote values file: https://raw.githubusercontent.com/config-sync-examples/helm-components/main/cert-manager-values.yaml
 `valuesMerge`     | ValuesMerge specifies how to treat ValuesInline with respect to ValuesFiles. Legal values: 'merge', 'override' (default), 'replace'. | replace
 
-<!--mdtogo-->
-
 [helm]: https://helm.sh/
 [charts]: https://helm.sh/docs/topics/charts/
 [helm template command]: https://helm.sh/docs/helm/helm_template/

krm-functions/sig-cli/render-helm-chart/examples/render-helm-chart-kustomize-inline-values/README.md

@@ -1,5 +1,86 @@
 # render-helm-chart: Kustomize Inline Values
 
-<!---
-TODO: Write up a doc for this example. 
--->
+### Overview
+
+This example demonstrates how to declaratively invoke the `render-helm-chart`
+function with kustomize using the `valuesInline` field.
+
+### Function invocation
+
+To use the function with kustomize, you can specify the `functionConfig`
+in your kustomization's `generators` field. This example uses inline values
+to use instead of the default values accompanying the chart:
+
+kustomization.yaml:
+```yaml
+generators:
+  - |-
+    apiVersion: v1alpha1
+    kind: RenderHelmChart
+    metadata:
+      name: demo
+      annotations:
+        config.kubernetes.io/function: |
+          container:
+            network: true
+            image: us.gcr.io/k8s-artifacts-prod/krm-functions/render-helm-chart:unstable
+    helmCharts:
+    - chartArgs:
+        name: ocp-pipeline
+        version: 0.1.16
+        repo: https://bcgov.github.io/helm-charts
+      templateOptions:
+        releaseName: moria
+        namespace: mynamespace
+        values:
+          valuesInline:
+            releaseNamespace: ""
+            rbac:
+              create: true
+              rules:
+                - apiGroups: [""]
+                  verbs: ["*"]
+                  resources: ["*"]
+```
+
+Then, to build the kustomization with kustomize v4:
+
+```shell
+kustomize build --enable-alpha-plugins --network .
+```
+
+### Expected result
+
+You should also be able to find the line `def releaseNamespace = ""` somewhere
+in your output, as well as the following: 
+
+```yaml
+apiVersion: rbac.authorization.k8s.io/v1
+kind: Role
+metadata:
+  name: moria-ocp-pipeline
+  namespace: mynamespace
+rules:
+- apiGroups:
+  - ""
+  resources:
+  - '*'
+  verbs:
+  - '*'
+---
+apiVersion: rbac.authorization.k8s.io/v1
+kind: RoleBinding
+metadata:
+  name: moria-ocp-pipeline
+  namespace: mynamespace
+roleRef:
+  apiGroup: rbac.authorization.k8s.io
+  kind: Role
+  name: moria-ocp-pipeline
+subjects:
+- kind: ServiceAccount
+  name: jenkins
+  namespace: mynamespace
+```
+
+which demonstrates that the correct values provided via `valuesInline` were used.

krm-functions/sig-cli/render-helm-chart/examples/render-helm-chart-kustomize-values-files/README.md

@@ -1,5 +1,81 @@
 # render-helm-chart: Kustomize Values Files
 
-<!---
-TODO: Write up a doc for this example. 
--->
+### Overview
+
+This example demonstrates how to declaratively invoke the `render-helm-chart`
+function with kustomize using multiple values files.
+
+### Function invocation
+
+To use the function with kustomize, you can specify the `functionConfig`
+in your kustomization's `generators` field. This example specifies multiple remote
+values files to use instead of the default values accompanying the chart:
+
+kustomization.yaml:
+```yaml
+generators:
+  - |-
+    apiVersion: v1alpha1
+    kind: RenderHelmChart
+    metadata:
+      name: demo
+      annotations:
+        config.kubernetes.io/function: |
+          container:
+            network: true
+            image: us.gcr.io/k8s-artifacts-prod/krm-functions/render-helm-chart:unstable
+    helmCharts:
+    - chartArgs:
+        name: ocp-pipeline
+        version: 0.1.16
+        repo: https://bcgov.github.io/helm-charts
+      templateOptions:
+        namespace: mynamespace
+        releaseName: moria
+        values:
+          valuesFiles:
+            - https://raw.githubusercontent.com/natasha41575/kpt-functions-catalog/a9c9cd765a05f7a7fb6923dbde4651b62c9c229c/examples/render-helm-chart-kustomize-values-files/file1.yaml
+            - https://raw.githubusercontent.com/natasha41575/kpt-functions-catalog/a9c9cd765a05f7a7fb6923dbde4651b62c9c229c/examples/render-helm-chart-kustomize-values-files/file2.yaml
+```
+
+Then, to build the kustomization with kustomize v4:
+
+```shell
+kustomize build --enable-alpha-plugins --network .
+```
+
+### Expected result
+
+You should also be able to find the line `def releaseNamespace = ""` somewhere
+in your output, as well as the following: 
+
+```yaml
+apiVersion: rbac.authorization.k8s.io/v1
+kind: Role
+metadata:
+  name: moria-ocp-pipeline
+  namespace: mynamespace
+rules:
+- apiGroups:
+  - ""
+  resources:
+  - '*'
+  verbs:
+  - '*'
+---
+apiVersion: rbac.authorization.k8s.io/v1
+kind: RoleBinding
+metadata:
+  name: moria-ocp-pipeline
+  namespace: mynamespace
+roleRef:
+  apiGroup: rbac.authorization.k8s.io
+  kind: Role
+  name: moria-ocp-pipeline
+subjects:
+- kind: ServiceAccount
+  name: jenkins
+  namespace: mynamespace
+```
+
+which demonstrates that the correct values provided via `valuesFiles` were used.