Skip to content

Latest commit

 

History

History
113 lines (76 loc) · 4.4 KB

contributor-guide.md

File metadata and controls

113 lines (76 loc) · 4.4 KB
Raw

Contributor guide

Tortoise

This document helps you in climbing the road to the contributor.

Please discuss changes before editing this page, even minor ones.

Rules

  • You must adhere to the linters configured in the repository. Avoid using //nolint except in extraordinary circumstances. Strive for compliance even with minor issues.
  • You must write unit tests for any new or modified functionality. Almost all changes should be accompanied by corresponding tests to ensure behavior is as expected.
  • Bugs always arise from insufficient or incorrect tests. You must update or add tests when fixing bugs to ensure the fix is valid. If you didn’t add a test, you didn’t fix the bug.
  • Do not test anything manually in your Kubernetes cluster. Instead, you must implement all testing in the e2e tests.
  • Do not bring any breaking change in Tortoise CRD. However, you may bring breaking changes in Golang functions or types within the repository - we're not developping the library and don't have to care much about downstream dependencies.

Suggestion

  • Enforce code-style issues with linters. When you want someone to fix a code-style, you can likely find a linter to detect such code-style issues in golangci-lint.

Useful Golang official documents

Contributors are expected to adhere to these official guidelines. Some of these recommendations are enforced by linters, while others are not.

Testing

The following command runs all tests (both unit tests and e2e tests) in the repository.

make test

E2e tests

Each Webhook and the controller have the integration tests.

Their test suite are mostly defined in Yaml files to add test cases easier, e.g., /controllers/testdata/.

Specifically about the controller's e2e test, it only simulates one reconciliation to simplify each test case. For example, if you expect Tortoise is changed to state-a in one reconciliation and to state-b in next reconciliation, you have to write two tests, one per reconciliation.

Auto-generate Integration Test Data(./controllers)

We have make test-update command to regenerate existing integration test data (./controllers/testdata/*/after/).

make test-update

When you implement some changes and it changes some test results, you can update test cases with it, without spending a waste time manually updating them.

But, make sure the generated test data is correct.

Also, note that a few test cases don't support this regeneration.

Debuggable Integration Test

We have make test-debug command to help you with debugging of the failing integration test.

make test-debug

If an integration test is failed, you'll see this message, and you can follow it to communicate with kube-apiserver to investigate the failure.

You can use the following command to investigate the failure:
$ kubectl --kubeconfig=/var/folders/3r/38tmpwm105d59kp_zlfbch0h0000gp/T/k8s_test_framework_1274319527/4210920706.kubecfg
When you have finished investigation, clean up with the following commands:
$ pkill kube-apiserver
$ pkill etcd
$ rm -rf /var/folders/3r/38tmpwm105d59kp_zlfbch0h0000gp/T/k8s_test_framework_1274319527

(This debuggable integration test is inspired by zoetrope/test-controller licensed under MIT License ❤️ )

Linters

First, make sure you have a necessary tool in your local machine.

make dependencies

The following command runs all enabled linters.

make lint

Some linters can fix some problems automatically by the following command.

make lint-fix

See [.golangci.yml] about the linters enabled in the repository.