Merge branch 'master' into starlark/v0.2

Author: Mengqi Yu

CONTRIBUTING.md

@@ -1,38 +1,9 @@
 # Contributing to kpt-functions-catalog
 
-We'd love to accept your contributions to this project. There are
-just a few small guidelines you need to follow.
+We'd love to accept your contributions to this project. There are just a few
+small guidelines you need to follow.
 
-## Community Guidelines
-
-This project follows [Google's Open Source Community Guidelines]
-and a [Code of Conduct].
-
-## How to Contribute
-
-This catalog contains configuration functions to fetch, display, customize,
-update, validate, and apply Kubernetes configuration. Contribute functions
-to this catalog by making the following changes:
-
-1. Make the code changes implementing the function and any unit tests. The code
-   belongs under [functions/] in the appropriate directory.
-2. Create an example of how to run your function and put it under [examples/].
-3. Test running your function example imperatively and declaratively in
-   [e2e tests]. These tests are run regularly and help catch regressions.
-4. Document your function in the config functions catalog on the [kpt website]
-   by following the [kpt contribution guidelines].
-5. Reach out to the maintainers to publish the function.
-
-Make PRs and request reviews for these changes. You can follow the pull request
-changes below:
-
-* [function implementation PR]
-* [example and e2e test PR]
-* [catalog documentation PR]
-
-### Code Changes
-
-#### Contributor License Agreement
+## Contributor License Agreement
 
 Contributions to this project must be accompanied by a Contributor License
 Agreement. You (or your employer) retain the copyright to your contribution;
@@ -44,38 +15,117 @@ You generally only need to submit a CLA once, so if you've already submitted
 one (even if it was for a different project), you probably don't need to do it
 again.
 
-#### Code reviews
+## Code reviews
 
 All submissions, including submissions by project members, require review. We
-use GitHub pull requests for this purpose. Consult
-[GitHub Help](https://help.github.com/articles/about-pull-requests/) for more
+use GitHub pull requests for this purpose. Consult [GitHub Help] for more
 information on using pull requests.
 
-### Documentation Changes
+## Community Guidelines
 
-This catalog is documented on the [kpt website]. Follow the
-[kpt contribution guidelines] to make docs changes.
+This project follows [Google's Open Source Community Guidelines] and
+a [Code of Conduct].
 
-Changes to other documentation such as examples and README files can follow the
-same pull request format as code changes.
+## Style Guides
+
+Contributions are required to follow these style guides:
+
+- [Error Message Style Guide]
+- [Documentation Style Guide]
+
+## How to Contribute
+
+### Repo Layout
+
+```shell
+├── examples: Home for all function examples
+│     ├── contrib: Home for all contrib function examples
+│     ├── curated_function_bar_example
+│     └── curated_function_foo_example
+├── functions
+│     ├── contrib: Home for all contrib function source code
+│     │     └── ts: Home for all typescript-based contrib function source code
+│     │         ├── Makefile
+│     │         └── contrib_ts_function_foo
+│     ├── go: Home for all golang-based curated function source code
+│     │     ├── Makefile
+│     │     ├── curated_go_function_bar
+│     │     └── curated_go_function_foo
+│     └── ts: Home for all typescript-based curated function source code
+│         ├── Makefile
+│         ├── curated_ts_function_bar
+│         └── curated_ts_function_foo
+├── scripts
+└── tests: Home for e2e tests
+```
+
+For each function, its files spread in the follow places:
+
+- `functions/` directory: Each function must have its own directory in one
+  of `functions/` sub-directory. In each function's directory, it must have
+  the following:
+    - Source code (and unit tests).
+    - A README.md file serving as the usage doc and will be shown in
+      the [catalog website].
+        - golang-based functions should follow [this template][golang-template].
+        - typescript-based functions should follow [this template][ts-template].
+    - A metadata.yaml file that follows the function metadata schema.
+    - A Dockerfile to build the docker container.
+- `examples/` directory: It contains examples for functions, and these examples
+  are also being tested as e2e tests. Each function should have at least one
+  example here. There must be a README.md file in each example directory, and it
+  should follow the [template][example-template].
+- The `tests/` directory contains additional e2e tests.
+
+### E2E Tests
+
+The e2e tests are the recommended way to test functions in the catalog. They are
+very easy to write and set up with our [e2e test harness].
+
+You can choose to put the e2e test in either the `examples/` directory or in the
+`tests/` directory depending on if it is worthwhile to be shown as an example.
+
+### Change Existing Functions
+
+You must follow the layout convention when you make changes to existing
+functions.
+
+If you implement a new feature, you must add a new example or modify existing
+one to cover it.
+
+If you fix a bug, you must add (unit or e2e) tests to cover that.
+
+### Contribute New Functions
+
+You must follow the layout convention when you contribute new functions.
 
 ## Contact Us
 
-Do you need a review or release of configuration functions? We’d love to hear
-from you!
+Do you need a review or release of functions? We’d love to hear from you!
 
 * Message our [Slack channel]
 * Join our [email list]
 
 [Google's Open Source Community Guidelines]: https://opensource.google.com/conduct/
+
 [Code of Conduct]: CODE_OF_CONDUCT.md
-[kpt website]: https://googlecontainertools.github.io/kpt/guides/consumer/function/
-[kpt contribution guidelines]: https://github.com/GoogleContainerTools/kpt/blob/master/CONTRIBUTING.md#adding-or-updating-catalog-functions
-[functions/]: functions/
-[examples/]: examples/
-[e2e tests]: tests/e2e.sh
-[function implementation PR]: https://github.com/GoogleContainerTools/kpt-functions-catalog/pull/61/
-[example and e2e test PR]: https://github.com/GoogleContainerTools/kpt-functions-catalog/pull/71
-[catalog documentation PR]: https://github.com/GoogleContainerTools/kpt/pull/785/
+
+[catalog website]: https://catalog.kpt.dev/
+
+[e2e test harness]: https://pkg.go.dev/github.com/GoogleContainerTools/kpt@v1.0.0-beta.2/pkg/test/runner
+
+[golang-template]: https://raw.githubusercontent.com/GoogleContainerTools/kpt-functions-catalog/master/functions/go/_template/README.md
+
+[ts-template]: https://raw.githubusercontent.com/GoogleContainerTools/kpt-functions-catalog/master/functions/ts/_template/README.md
+
+[example-template]: https://raw.githubusercontent.com/GoogleContainerTools/kpt-functions-catalog/master/examples/_template/README.md
+
 [Slack channel]: https://kubernetes.slack.com/channels/kpt/
+
 [email list]: https://groups.google.com/forum/?oldui=1#!forum/kpt-users
+
+[error message style guide]: https://github.com/GoogleContainerTools/kpt/blob/main/docs/style-guides/errors.md
+
+[documentation style guide]: https://github.com/GoogleContainerTools/kpt/blob/main/docs/style-guides/docs.md
+
+[GitHub Help]: https://help.github.com/articles/about-pull-requests/

Makefile

@@ -56,7 +56,6 @@ push: ## Push images to registry. WARN: This operation should only be done in CI
 
 site-generate: ## Collect function branches and generate a catalog of their examples and documentation using kpt next.
 	rm -rf ./site/*/
-	# GO111MODULE=on go get -v github.com/GoogleContainerTools/kpt@next
 	(cd scripts/generate_catalog/ && go run . ../.. ../../site)
 
 site-run: ## Run the site locally.

VERSIONING.md

@@ -0,0 +1,118 @@
+# Versioning
+
+## SemVer and shorter SemVer
+
+We use [semantic versioning] for all of our images. The images with fully
+specified version (e.g. `vX.Y.Z`) are immutable and will never be changed. We
+also support a shorter version of semantic versioning. E.g.
+`v<major>` and `v<major>.<minor>`.
+
+The shorter version of semantic versioning is going to be floating tags:
+
+- `v<major>.<minor>` always points to `v<major>.<minor>.X` where X is the latest
+  (largest) patch version number. E.g. assume `v1.2` points `v1.2.0` initially.
+  After `v1.2.1` is released, `v1.2` now points to `v1.2.1`.
+
+- `v<major>` always points to `v<major>.X` where X is the latest (largest) minor
+  version number. E.g. assume `v1` points `v1.2.0` initially. After `v1.3.0` is
+  released, `v1` now points to `v1.3.0`. After `v1.3.1` is released, `v1` now
+  points to `v1.3.1`.
+
+Note: We do NOT support the `latest` tag, since we cannot provide any
+compatibility guarantee for it, and the pipeline won’t produce deterministic
+results.
+
+## User-facing Surfaces
+
+All functions in the catalog comply with the [function spec]. To learn more
+about the functions concept,
+see [here](http://kpt.dev/book/02-concepts/03-functions).
+
+There are 2 user-facing surfaces for a function:
+
+- The `functionConfig`
+- The function behavior
+
+### functionConfig Surface
+
+A `functionConfig` can be either a core resource (e.g. `ConfigMap`) or a custom
+resource. If the `functionConfig` is a CRD, it can be versioned independently as
+a normal CRD.
+
+### Function Behavior Surface
+
+#### What are NOT part of the function behavior surface
+
+- The formatting of serialization for output items and results. e.g. yaml
+  indentation and order of fields in a map.
+- The order of resources in the output items.
+- The order of result items in the results.
+- The content of the unstructured messages in the results.
+
+#### What are part of the function behavior surface
+
+- The supported `functionConfig`:
+    - If the function supports `ConfigMap` as `functionConfig`, the supported
+      fields in the `ConfigMap`.
+    - If the function supports a custom resource as `functionConfig`, the
+      supported versions of the custom resource.
+- How the function behave given the input items and `functionConfig`:
+    - The remaining aspects of the output items that are not mentioned in the
+      previous section.
+    - The remaining aspects of the results that are not mentioned in the
+      previous section.
+
+For example, if the `kubeval` function stops supporting
+the `ignore_missing_schemas` option in the `ConfigMap`, it will be a breaking
+change.
+
+Another example, if the `set-namespace` function stops supporting custom
+resource of apiVersion `fn.kpt.dev/v1alpha1` and kind `SetNamespace`, it will be
+a breaking change.
+
+### Breaking Changes
+
+We define a breaking change as: For any given input (including `input items`,
+`functionConfig` and OpenAPI), the function produces a different output
+(including output items, results) that are part of the user-facing surface.
+
+### Backwards Compatibility
+
+For post v1.0.0 versions, we will:
+
+- Bump major version: There are breaking changes.
+
+- Bump minor version: There are backward-compatible features.
+
+- Bump patch version: There are only bug fixes and security fixes (e.g.
+  dependency package non-breaking version bump and base image non-breaking
+  version bump).
+
+For pre v1.0.0 versions, the major version is always `0` and we will:
+
+- Bumping minor version: There are breaking changes.
+
+- Bumping patch version: In all other cases, including backward-compatible
+  features, bug fixes and security fixes.
+
+## Best Practices
+
+There are 2 ways to specify your desired version:
+
+- You can fully specify the whole SemVer: The benefits are that you get
+  immutable infrastructure, and you control when to upgrade functions.
+- You can use floating tags (e.g. `vX.Y` and `vX`): The benefits are that there
+  are less maintenance toil, since it automatically pick up the security and bug
+  fixes.
+
+Don't use `latest` tag if you use your own function images, since
+it’s [not a best practice] for production and also it
+is [not recommended by kubernetes].
+
+[not a best practice]: https://vsupalov.com/docker-latest-tag/
+
+[not recommended by kubernetes]: https://kubernetes.io/docs/concepts/configuration/overview/#container-images
+
+[semantic versioning]: https://semver.org/
+
+[function spec]: https://github.com/kubernetes-sigs/kustomize/blob/master/cmd/config/docs/api-conventions/functions-spec.md

examples/apply-setters-simple/.expected/diff.patch

@@ -26,4 +26,4 @@ index b521905..0d10662 100644
  environments: # kpt-set: ${env}
 +  - prod
    - dev
--  - stage
+-  - stage