[DX/tests] - Update doc tutorials programatically for any PR change

[camilamacedo86]

What do you want to happen?

Description

Currently, we have the following samples which are used in the docs:

• Component Config: https://github.com/kubernetes-sigs/kubebuilder/tree/master/docs/book/src/component-config-tutorial/testdata
• CronJob Tutorial: https://github.com/kubernetes-sigs/kubebuilder/tree/master/docs/book/src/cronjob-tutorial/testdata
• Multiversion-tutorial: https://github.com/kubernetes-sigs/kubebuilder/tree/master/docs/book/src/multiversion-tutorial/testdata

You can see that the docs are using the samples and the info provided on them are comments in the source code generated.
However, it has been very thought we keep updated with the changes performed in the scaffolds. Currently, we need to:

• Run the helpers scripts under it samples dir (generate_cronjob.sh, generate_multiversion.sh, generate_componentconfig.sh )
• Run make all
• Then, compare the local branch with the master branch and then re-add the missing files and all code generated for the samples as the comments back
• Run make all again to ensure and compare again to see if we are not missing anything

Goal

The goal of this task is we programmatically ensure that all samples will be updated for any pull request sent to the project. It. will help us keep the docs and update and improve the DX for contributors. Also, it can help us check the changes in the review process which also help us to easily ensure them.

Note that we have a shell script generate.sh which is called via the makefile target [make generate] (https://github.com/kubernetes-sigs/kubebuilder/blob/master/Makefile#L65-L67) to re-gen all samples under the testdata dir.

See that in the CI we check if the samples are updated or not and we do not lot contributions that change the scaffold go forward and get merged without the authors ensuring that they executed the make generate locally to keep all updated. (You can check the GitHub Action: https://github.com/kubernetes-sigs/kubebuilder/blob/master/.github/workflows/testdata.yml)

Proposed Solution

• We use the Test Context utils to run all commands to generate the book testsdata samples, e.g: https://github.com/kubernetes-sigs/kubebuilder/blob/master/test/e2e/v3/generate_test.go#L132-L231
• Then, we use the utils to replace and insert the code source of the book samples as its comments back.

Note that we do something very similar in the SDK project using the same implementations to ensure that is samples under testdatawill have the required code changes. See: https://github.com/operator-framework/operator-sdk/blob/master/hack/generate/samples/internal/go/v3/memcached_with_webhooks.go

• We also need to call this implementation in the make generate target to ensure that it will be re-gen as tested in the CI.

Extra info

• We can have one PR to implement each book data to split the required work and make it easier
• I'd recommend we get started by automating the Component Config because this one is a small project in the book
• Be aware that for the samples CronJob Tutorial and Multiversion-tutorial the shell scripts generate_cronjob.sh, generate_multiversion.sh are missing steps and we usually need to add files back. In this case, would be nice to follow all the whole docs/tutorials and ensure that we are following the exact same steps that you are asking users to do. It will also help us ensure our guidance and please feel free to push PR's contributions to the docs if you find any issue with them.

Extra Labels

No response

Implementation solution for: #782

Current Status

• - Component Config is done: 📖 : update ComponentConfig tutorial #3181
• - CronJob Tutorial is done; 🌱 Update cronjob-tutorial automatically #3231
• - Multiversion-tutorial: TODO

[jmrodri]

This proposal makes sense to me. Anything that will improve keeping the samples updated is great.

[shuheiktgw]

Hi @camilamacedo86, can I work on this issue as my first contribution to kubebuilder project? 🙏

[camilamacedo86]

Sure, I'd recommend we begin by trying. to check this approach with the Component Config because this one is a smaller sample the docs
.

[shuheiktgw]

/assign

[shuheiktgw]

Sorry that I could not find time to work on this for the past few weeks, but I've finally started working on it 🙇

[camilamacedo86]

That is fine. No worry.

[shuheiktgw]

Sorry, let me clarify what we need to do here in the component-config's case as an example!

Then, we use the utils to replace and insert the code source of the book samples as its comments back.

I'm not sure where "the code source of the book samples" is located... Would you give me some pointers to it?