Improve documentation

[kaizakin]

Our current documentation docs/ is kinda vague and minimal

It would be better if we could have more samples & a page documenting the directory structure.

additionally document the major dependencies and why is it used.

suggest your ideas as well

[kaizakin]

for example:

---

• pkg/apis/build/ holds the generated API types for both versions — v1alpha1/ and v1beta1/ — including the hand-written *_conversion.go files that implement the ConvertTo/ConvertFrom methods discussed above. If you're adding a field to any of the four CRDs, this is where the Go struct lives, alongside the corresponding conversion-webhook logic you'll need to update on both sides.
• pkg/reconciler/ contains one subpackage per controller — build, buildrun (plus its large resources/ subpackage, which is where the executor generator, source/output step builders, and status-condition translation all live), buildstrategy, clusterbuildstrategy, buildlimitcleanup, and buildrunttlcleanup. This is where you'll spend most of your time for any change to reconcile behavior.
• pkg/validate/ is the validation registry described earlier — one file per validator (secrets, strategy references, source URL, output, env vars, triggers, node selector, tolerations, scheduler name, runtime class, and more), all implementing the shared BuildPath interface.
• pkg/controller/controller.go is the single place all six reconcilers get registered onto one shared controller-runtime manager — a good starting point if you want to see the whole system's startup sequence in one file.
• pkg/config/ parses environment variables into a typed Config struct — this is where BUILDRUN_EXECUTOR, the four helper-binary image env vars, timeouts, and Prometheus bucket settings all get read.
• pkg/webhook/ is the CRD conversion webhook (not admission validation, despite the name) — conversion/ has the actual HTTP handler and per-kind conversion dispatch, tlsconfig/ just builds a Go tls.Config (certs themselves come from hack/setup-webhook-cert.sh, not this package).
• pkg/git/, pkg/image/, pkg/bundle/, pkg/util/, pkg/env/, pkg/volumes/, pkg/metrics/, pkg/ctxlog/ are focused support packages — git operations, image/registry helpers, OCI-bundle handling, small utilities, environment-variable validation (including the forbidden-name checks used by validate.Envs), volume-merging logic, Prometheus metric definitions, and a structured-logging wrapper around logr, respectively.
• cmd/ is where the actual binaries live, and it splits cleanly into two groups: cmd/shipwright-build-controller and cmd/shipwright-build-webhook are the two long-running Deployments (the controller manager and the conversion webhook), while cmd/git, cmd/bundle, cmd/image-processing, and cmd/waiter are small, single-purpose binaries that never run as their own Deployment — instead they're baked into container images (via ko://github.com/shipwright-io/build/cmd/... references, see deploy/500-controller.yaml) and injected as steps inside the generated TaskRun/PipelineRun pod, which is what actually clones source, unpacks bundles, waits for local copies, and pushes/annotates the final image at build time.
• images/ holds the Dockerfiles that wrap those cmd/ binaries into runnable container images (images/git, images/base, images/image-processing, images/waiter) — if you're changing what tools are available inside, say, the git-clone step (adding git-lfs support, for instance), this is where the base image gets built, separately from the Go code in cmd/git.
• deploy/ has the raw Kubernetes manifests for installing Shipwright itself — numbered roughly in apply order (namespace, RBAC, service accounts, the controller Deployment, the webhook Deployment) — plus deploy/crds/ holding the generated CRD YAML (including the conversion.webhook block wired to the webhook Service).
• samples/ is split by API version (v1alpha1/, v1beta1/) and then by kind (build/, buildrun/, buildstrategy/) — this is the fastest way to see a real, working ClusterBuildStrategy (Buildah, Buildpacks, Kaniko, etc.) rather than trying to construct one from the docs alone.
• test/ mirrors the project's testing strategy in its own layout: test/integration and test/e2e/{v1alpha1,v1beta1} hold suites that run against a real cluster (KinD, per test/kind/), test/v1alpha1_samples/test/v1beta1_samples hold fixture YAML those tests apply, and test/utils holds shared test helpers per API version.
• hack/ is the usual grab-bag of contributor/CI scripts — installing KinD/Tekton/trivy/counterfeiter for local dev, code generation (update-codegen.sh, generate-fakes.sh), and, notably, setup-webhook-cert.sh and patch-crds-with-conversion.sh, which are the actual mechanism behind the self-managed webhook TLS certs described in the architecture section — there's no cert-manager dependency here, just this script driving a Kubernetes CSR.
• docs/ is worth reading before you touch strategy-related code specifically — docs/buildstrategies.md documents the full system-parameter/system-result vocabulary that every BuildStrategy author needs to know, and it's more precise than trying to infer the convention purely from sample YAML.
• version/ is a single small package that just tracks the build-time version string — unrelated to API versioning, despite the name similarity to v1alpha1/v1beta1.

---

Disclaimer: This is generated using AI

[Atharva2093]

Can you assign me this issue.

[kaizakin]

sure.

please make sure all the examples/tutorials you add are well tested locally

I'd suggest take your time, well understand the codebase
ping any of us if you run into any doubts and you're welcome to join the community meeting today evening

/assign @Atharva2093

[Atharva2093]

@kaizakin how can i join the meet ?

[kaizakin]

here you go:
link