Skip to content

Latest commit

 

History

History
243 lines (172 loc) · 7.98 KB

CONTRIBUTING.md

File metadata and controls

243 lines (172 loc) · 7.98 KB
Raw

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.

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; this simply gives us permission to use and redistribute your contributions as part of the project. Head over to https://cla.developers.google.com/ to see your current agreements on file or to sign a new one.

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

All submissions, including submissions by project members, require review. We use GitHub pull requests for this purpose. Consult GitHub Help for more information on using pull requests.

Community Guidelines

This project follows Google's Open Source Community Guidelines and a Code of Conduct.

Style Guides

Contributions are required to follow these style guides:

How to Contribute

Repo Layout

├── examples: Home for all curated function examples
│     ├── curated_function_bar_example
│     └── curated_function_foo_example
├── functions
│     ├── 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
├── contrib
│     ├── functions
│     │     ├── go: Home for all golang-based contrib function source code
│     │     └── ts: Home for all typescript-based contrib function source code
│     └── examples: Home for all contrib function examples.
├── scripts
├── tests: Home for e2e tests
└── build
      └── docker
          ├── go: Home for default golang Dockerfile
          │    └── Dockerfile
          └── ts: Home for default typescript Dockerfile
               └── Dockerfile

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.
    • A metadata.yaml file that follows the function metadata schema.
    • (Optional) A Dockerfile to build the docker container. If a Dockerfile is not defined, the default Dockerfile for the language will be used.
  • 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.
  • The tests/ directory contains additional e2e tests.
  • master branch should should contain examples with the unstable tag for your function images. When you release the function version that tag should have the samples and tests that match the function version.

For golang-based functions, you need to generate some doc related variables from the README.md by running

$ cd functions/go
$ make generate

Tests

Unit Tests

To run all unit tests

$ make unit-test

Building a function image

Note: We use docker buildx to build images. Please ensure you have it installed.

To build all function images

$ make build

To build a single function image (e.g. apply-setters)

$ cd functions/go
$ make apply-setters-BUILD

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 find all the supported options and expected test directory structure here.

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.

Note: The e2e tests don't build the images. So you need to ensure you have built the latest image(s) before running any e2e tests.

To test a specific example or the e2e test, run

$ cd tests/e2etest
$ go test -v ./... -run TestE2E/../../examples/$EXAMPLE_NAME
# To test the example in contrib
$ go test -v ./... -run TestE2E/../../contrib/examples/$EXAMPLE_NAME

If you encounter some test failure saying something like "actual diff doesn't match expected" or "actual results doesn't match expected", you can update the expected diff.patch or results.yaml by running the following commands:

# Update one example
$ KPT_E2E_UPDATE_EXPECTED=true go test -v ./... -run TestE2E/../../examples/$EXAMPLE_NAME
# Update one example in contrib 
$ KPT_E2E_UPDATE_EXPECTED=true go test -v ./... -run TestE2E/../../contrib/examples/$EXAMPLE_NAME

# Update all examples
$ KPT_E2E_UPDATE_EXPECTED=true go test -v ./...

Most contributors don't need this, but if you happen to need to test all examples and e2e tests, run the following command

$ make e2e-test

Doc Verifier

We have a script to ensure the usage docs and the examples are consistent. Please ensure it's passing by running:

$ ./scripts/verify-docs.py

This script requires Python 3, pyyaml and mdrip which is a CLI tool.

To install pyyaml, run the following command:

pip install pyyaml

To install mdrip, run the following commands:

$ go install github.com/monopole/mdrip@v1.0.2

And you need to ensure $GOPATH/bin is in your PATH.

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.

You need to add new function name to the respective language Makefiles.

  • functions/go/Makefile for golang.
  • functions/ts/Makefile for typescript.

Contact Us

Do you need a review or release of functions? We’d love to hear from you!