docs: write the Kubebuilder reference, translate first-commiter

[whg517]

Summary

Two pages, both language trees. After this, every placeholder that can be filled from source is filled — the three remaining ones are blocked on things source research cannot supply.

docs(reference): write the Kubebuilder reference

Replaces a one-line placeholder that also misspelled its own title as "Kuberbuilder". Scoped to the parts of Kubebuilder this project actually uses rather than restating the upstream book.

Facts come from the repositories: the PROJECT file and its domain: kubedoop.dev / layout: go.kubebuilder.io/v4, the controller-gen v0.19.0 and kustomize v5.7.1 versions pinned in the Makefile, and a marker inventory taken by grepping the API packages of operator-go, zookeeper-operator and spark-k8s-operator — so the tables list markers genuinely in use, not everything Kubebuilder offers.

It documents a live bug as the worked example

Markers are case-sensitive. +kubebuilder:validation:optional with a lowercase o is not a marker. controller-gen ignores it silently, and the field falls back to the rule that a field without omitempty is required. Nothing warns, the build succeeds, and the field lands in the CRD's required list.

zookeeper-operator has exactly this today, on ClusterConfigSpec.ListenerClass:

// +kubebuilder:validation:optional          ← ignored
// +kubebuilder:validation:Enum="cluster-internal";"external-unstable"
// +kubebuilder:default="cluster-internal"
ListenerClass ListenerClass `json:"listenerClass"`   // no omitempty either

and the generated CRD shows the consequence:

required:
- listenerClass

A field with a default, clearly intended to be optional, is marked required. The page gives the grep that reveals this class of problem. This is a bug in zookeeper-operator, not in this repository — worth a separate issue there.

docs(developer-manual): translate first-commiter, and fix two errors in it

The English page held Chinese prose and was byte-identical to its zh counterpart — the second of the two cases AGENTS.md flags, and the last one. The English tree is now English throughout.

Translating surfaced two errors present in both copies:

Was	Problem
git remote add upstream https://github.com/kubedoop.dev/docs	kubedoop.dev is the documentation site's domain, not a GitHub organisation. That command could never have worked. It is zncdatadev/docs
"远程的 upstream (swoole/swoole-src)"	Leftover from the Swoole project this text was adapted from

While rewriting: replaced the two-entry feature/fix list with the full branch-naming table the project actually uses, switched git checkout to git switch, added the --force-with-lease step a first-time contributor hits the moment they rebase an already-pushed branch, and pointed the pre-PR check at npm run verify.

Testing

• npm run verify exits 0 — 52 files linted with 0 errors, both locales built
• All relative links resolve (onBrokenLinks: 'throw')
• No Chinese prose left anywhere in docs/ — checked by scanning every file

Stage 2 status

3 placeholders remain, none of them fillable from source:

Page	Blocked on
core-concepts/resources/database.md	No operator consumes DatabaseConnection; credential keys and default ports are undefined (see #38)
faq.md	Real user questions
release-notes.md	Release history

The last two need maintainer input rather than research.

🤖 Generated with Claude Code