From a25ed2df050d6999a7712d9361d72e153d981c06 Mon Sep 17 00:00:00 2001 From: Akihito INOH Date: Mon, 26 Apr 2021 13:44:52 +0900 Subject: [PATCH 1/6] doc: fix markdown format about tools-branch This commit fix markdown format error in VERSIONING.md about ref to tools-branch link. --- VERSIONING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/VERSIONING.md b/VERSIONING.md index e7b22ebba83..a364a5c21fc 100644 --- a/VERSIONING.md +++ b/VERSIONING.md @@ -57,7 +57,7 @@ the desired next version. Once the PR is merged, Google Cloud Build will take care of building and publishing the artifacts. [envtest-ref]: https://book.kubebuilder.io/reference/artifacts.html -[tools-branch]: https://github.com/kubernetes-sigs/kubebuilder/tree/tools-releases) +[tools-branch]: https://github.com/kubernetes-sigs/kubebuilder/tree/tools-releases ## Versioning From e3b52123311a00a8c9c725f0d592ee2ba859b1ea Mon Sep 17 00:00:00 2001 From: Solly Ross Date: Mon, 26 Apr 2021 10:58:47 -0700 Subject: [PATCH 2/6] Fix issue templates Validation appears to have increased slightly, and some deprecated fields were switch up. This made it impossible to file issues in KubeBuilder, which is... suboptimal. This fixes that, so we can once again open the receive bugs :-) --- .github/ISSUE_TEMPLATE/bug_report.yaml | 4 ++-- .github/ISSUE_TEMPLATE/config.yml | 2 +- .github/ISSUE_TEMPLATE/feature_request.yaml | 2 +- 3 files changed, 4 insertions(+), 4 deletions(-) diff --git a/.github/ISSUE_TEMPLATE/bug_report.yaml b/.github/ISSUE_TEMPLATE/bug_report.yaml index 2fb6815d07f..40c279c87fa 100644 --- a/.github/ISSUE_TEMPLATE/bug_report.yaml +++ b/.github/ISSUE_TEMPLATE/bug_report.yaml @@ -1,5 +1,5 @@ name: Bug Report -about: Problems and issues with code or docs +description: Problems and issues with code or docs labels: - kind/bug body: @@ -126,7 +126,7 @@ body: - type: dropdown attributes: - label: " " + label: "Extra Labels" description: | If this is *also* a documentation request, etc, please select that below. multiple: true diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml index 334bc239e2a..18121c08a39 100644 --- a/.github/ISSUE_TEMPLATE/config.yml +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -1,5 +1,5 @@ # allow free form issues as an escape hatch. This can be taken away if people abuse it ;-) -blank_issues_enabled: true +blank_issues_enabled: true # link to CR and CT for easier access contact_links: diff --git a/.github/ISSUE_TEMPLATE/feature_request.yaml b/.github/ISSUE_TEMPLATE/feature_request.yaml index dd75da985ab..ed2c09c8edf 100644 --- a/.github/ISSUE_TEMPLATE/feature_request.yaml +++ b/.github/ISSUE_TEMPLATE/feature_request.yaml @@ -81,7 +81,7 @@ body: - type: dropdown attributes: - label: " " + label: "Extra Labels" description: | If this is *also* a documentation request, etc, please select that below. multiple: true From fc4f99aaeb0a2827228d903f78fe38e7fbb15a3f Mon Sep 17 00:00:00 2001 From: Solly Ross Date: Wed, 7 Apr 2021 14:30:12 -0700 Subject: [PATCH 3/6] Fix advice on using manager's client in tests Previous documentation erroneously misconfigured the cronjob's tutorial to use the manager's client everywhere, which is poor practice because using a cache client in assertions leads to flaky & slow tests. A new PR overcorrected, and switched both assertions *and* the reconciler to use a live client, which is also wrong, because the reconciler needs to use a manager's client to function properly. This corrects the documentation to indicate that reconcilers should use managers' clients, and test assertions should use a live client, and adds a full explanation as to why. --- .../testdata/project/controllers/suite_test.go | 18 ++++++++++-------- 1 file changed, 10 insertions(+), 8 deletions(-) diff --git a/docs/book/src/cronjob-tutorial/testdata/project/controllers/suite_test.go b/docs/book/src/cronjob-tutorial/testdata/project/controllers/suite_test.go index 60b8a4e4578..0412182e33d 100644 --- a/docs/book/src/cronjob-tutorial/testdata/project/controllers/suite_test.go +++ b/docs/book/src/cronjob-tutorial/testdata/project/controllers/suite_test.go @@ -115,14 +115,16 @@ var _ = BeforeSuite(func() { The only difference is that the manager is started in a separate goroutine so it does not block the cleanup of envtest when you’re done running your tests. - It is not recommended to use the manager client in tests because it is not strongly consistent. Indeed, the manager - client is designed to do the "right thing" for controllers by default which is to read from caches. The best solution - is to instantiate a new client using client.New for tests (as k8sClient above). It will provide a client that reads - directly from the API meaning that you can write tests expecting read-after-write consistency. - - However, keep in mind that you should not do this in the controller's conciliation loop (read an object after you have - written it). Kubernetes favors an approach where you first do some reads, process and then do some writes and return. - This way, you let the queue take care of the next cycle of readings if they are necessary. + Note that we set up both a "live" k8s client, separate from the manager. This is because when making assertions in + tests, you generally want to assert against the live state of the API server. If you used the client from the + manager (`k8sManager.GetClient`), you'd end up asserting against the contents of the cache instead, which is slower + and can introduce flakiness into your tests. We could use the manager's `APIReader` to accomplish the same thing, + but that would leave us with two clients in our test assertions and setup (one for reading, one for writing), and + it'd be easy to make mistakes. + + Note that we keep the reconciler running against the manager's cache client, though -- we want our controller to + behave as it would in production, and we use features of the cache (like indicies) in our controller which aren't + available when talking directly to the API server. */ k8sManager, err := ctrl.NewManager(cfg, ctrl.Options{ From acb91e6fa84c3e30f794474e4b8daf8b5da86409 Mon Sep 17 00:00:00 2001 From: Solly Ross Date: Wed, 7 Apr 2021 14:32:37 -0700 Subject: [PATCH 4/6] Run book cronjob unit tests are run in `make test` This makes sure that the cronjob's tutorial's tests are run in make test, which should avoid breaking the book again. --- Makefile | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/Makefile b/Makefile index 5f0173b0776..071e1a9c49f 100644 --- a/Makefile +++ b/Makefile @@ -88,7 +88,7 @@ golangci-lint: ##@ Tests .PHONY: test -test: test-unit test-integration test-testdata ## Run the unit and integration tests (used in the CI) +test: test-unit test-integration test-testdata test-book ## Run the unit and integration tests (used in the CI) .PHONY: test-unit test-unit: ## Run the unit tests @@ -119,3 +119,7 @@ test-e2e-local: ## Run the end-to-end tests locally .PHONY: test-e2e-ci test-e2e-ci: ## Run the end-to-end tests (used in the CI)` ./test/e2e/ci.sh + +.PHONY: test-book +test-book: ## Run the cronjob tutorial's unit tests to make sure we don't break it + cd ./docs/book/src/cronjob-tutorial/testdata/project && make test From 1de6c3ff6e6891b6490e3e849f5ea7017dd12c60 Mon Sep 17 00:00:00 2001 From: Solly Ross Date: Wed, 7 Apr 2021 14:44:47 -0700 Subject: [PATCH 5/6] Use `make tests` in CI The CI previously duplicated the contents of `make test` in a separate script. This just makes that script call `make test` instead. --- test.sh | 11 +++-------- 1 file changed, 3 insertions(+), 8 deletions(-) diff --git a/test.sh b/test.sh index 3f17ef45342..033c9f7d00e 100755 --- a/test.sh +++ b/test.sh @@ -14,11 +14,6 @@ # See the License for the specific language governing permissions and # limitations under the License. -source test/common.sh - -header_text "Running kubebuilder unit tests" -go test -race -v ./pkg/... - -./test/integration.sh - -./test/testdata/test.sh +# prow calls this file currently, but we can just use `make test` to test +# the set of things we want. +make test From 9facdc4ef606565a14e7d0921dbac65b166198e8 Mon Sep 17 00:00:00 2001 From: Camila Macedo Date: Mon, 18 Jan 2021 20:29:39 +0000 Subject: [PATCH 6/6] :book: update the docs over regards book-v3 branch --- CONTRIBUTING.md | 4 ++-- RELEASE.md | 2 +- VERSIONING.md | 4 ++-- 3 files changed, 5 insertions(+), 5 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index ae0aa1564da..9e7a732777a 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -95,8 +95,8 @@ separately. The docs are published off of three branches: -- `book-v2`: [book.kubebuilder.io](https://book.kubebuilder.io) -- current - docs +- `book-v3`: [book.kubebuilder.io](https://book.kubebuilder.io) -- current docs +- `book-v2`: [book-v2.kubebuilder.io](https://book.kubebuilder.io) -- legacy docs - `book-v1`: [book-v1.book.kubebuilder.io](https://book-v1.book.kubebuilder.io) -- legacy docs diff --git a/RELEASE.md b/RELEASE.md index 5eda684f2fe..15f2c11e8ac 100644 --- a/RELEASE.md +++ b/RELEASE.md @@ -5,7 +5,7 @@ The Kubebuilder Project is released on an as-needed basis. The process is as fol 1. An issue is proposing a new release with a changelog since the last release. You will need to use the [kubebuilder-release-tools][kubebuilder-release-tools] to generate the notes. See [here][release-notes-generation] 1. All [OWNERS](OWNERS) must LGTM this release 1. An OWNER runs `git tag -s $VERSION` and pushes the tag with `git push $VERSION`. Note that after the OWNER push the tag the CI will automatically add the release notes and the assets. -1. A PR needs to be created to merge `release-X` branch into `book-vX` to pick up the new docs. +1. A PR needs to be created to merge `master` branch into `book-v3` to pick up the new docs. 1. The release issue is closed 1. An announcement email is sent to `kubebuilder@googlegroups.com` with the subject `[ANNOUNCE] kubebuilder $VERSION is released` diff --git a/VERSIONING.md b/VERSIONING.md index a364a5c21fc..185f4b437c3 100644 --- a/VERSIONING.md +++ b/VERSIONING.md @@ -34,7 +34,7 @@ the latest controller-tools release. That info is stored in ## Book Releases The book's main version (https://book.kubebuilder.io) is published off of -the [book-v2][book-branch] (a version built off the main branch can be +the [book-v3][book-branch] (a version built off the main branch can be found at https://master.book.kubebuilder.io). Docs changes that aren't specific to a new feature should be @@ -43,7 +43,7 @@ The cherry-picks will automatically be published to the book once their PR merges. **When you publish a KubeBuilder release**, be sure to also submit a PR -that merges the main branch into [book-v2][book-branch], so that it +that merges the main branch into [book-v3][book-branch], so that it describes the latest changes in the new release. [book-branch]: https://github.com/kubernetes-sigs/kubebuilder/tree/tools-releases