Clarify a few points on Development Documentation.

[jgao1025]

Background

When doing #738 and following dev guide to build a local environment, a few steps better to be improved for the clarification.

The benefit of the changes

It would reduce the mount of time when a new developer try to contribute by scratch. For instance, I spent 5 hours+ searching for a solution to install a standalone Kubernetes cluster and eventually found Minikube. However, I wasn't aware that I could simply install Kind and get everything working without needing to change any environment settings.

The changes to the Documentation

1. In the Prerequisites section, it lists the software required: Go, Kubectl, and Kind. While Go and Kubectl are well-known, Kind might be unfamiliar to some. It would be helpful to specify that Kind is a standalone Kubernetes cluster, so newcomers understand its purpose.

2. The Go language requires a specific version to build the project. It would be useful to specify the version needed, so contributors can avoid the hassle of installing and then uninstalling an outdated version. The error msg I met when I tried to build the project.

$ make generate
hack/update-codegen.sh
go: go.mod requires go >= 1.22.0 (running go 1.21.11; GOTOOLCHAIN=local)
syntax error at -e line 1, near "< )
"
Execution of -e aborted due to compilation errors.
Go v or later is required to run code generation
make: *** [Makefile:65: update-codegen] Error 1

3. Building the source code requires shasum. On Fedora Linux, this command is called sha1sum. A workaround is to create a symbolic link with the following command: ln -s /usr/bin/sha1sum /usr/bin/shasum. I would be appreciate if this could be added in the doc too. The error msg is like below:

hack/update-codegen.sh: line 220: shasum: command not found
Downloaded protoc binary failed checksum.
make: *** [Makefile:65: update-codegen] Error 1

4. The Dev Guide currently covers building CRDs from source code and verifying the code before submitting a PR. It would be helpful to also include instructions on deploying the built CRDs to an existing Kind server. Additionally, providing a reference to Getting Started with Gateway API would offer a consistent starting point, guiding users from initial setup to practical implementation.

[youngnick]

This is outstanding feedback, thanks @jgao1025! To be honest, this is probably one of the best first PRs I can imagine, if you're up for it.

The documentation is in the repo in site-src, and the Documentation section of that page is still accurate.

[jgao1025]

This is outstanding feedback, thanks @jgao1025! To be honest, this is probably one of the best first PRs I can imagine, if you're up for it.

The documentation is in the repo in site-src, and the Documentation section of that page is still accurate.

Hi @youngnick Thanks for your comment. I can raise a PR to fix item 1-3, but I struggled to work out item 4. The instruction is missing some key steps that I found challenging to follow. For example, it doesn't include the process for creating the foo-svc service and the associated web servers. Additionally, the instructions need to cover installing the Gateway API CRDs from the source code and finding a compatible controller that supports those CRDs.

/assign

Oh, just raise a PR. That's a fast one. :)