Project: Carvel (App Definition and Development / Application Definition & Image Build)
File: dev.md

```bash git clone https://github.com/carvel-dev/ytt ./src/github.com/carvel-dev/ytt export GOPATH=$PWD cd ./src/github.com/carvel-dev/ytt ./hack/build.sh ./hack/test-unit.sh ./hack/test-e2e.sh ./hack/test-all.sh ``` To keep source code documentation up to date, ytt uses . To document a type, variable, constant, function, or a package, write a regular comment directly preceding its declaration that begins with the name of the element it describes. See the for examples. When contributing new source code via a PR, the will ensure that godocs are included in the changes. To view the docs install godoc: `go get -v golang.org/x/tools/cmd/godoc` Start the server: `godoc -http=:6060` and visit . The go module was renamed from `github.com/k14s` to `github.com/carvel-dev/ytt` in February 2022. Carvel started out as a suite named "k14s" short for Kubernetes Tools. For those interested in extending and improving `ytt`, below is a quick reference on the structure of the source code: is the top level call site for the template command allows reading files from filesystem keeps read files from the filesystem in memory for later access `load(...)` directive goes through `TemplateLoader` to load files parses YAML and tracks YAML node annotations (metas) generates Starlark template based on yamlmeta package structures parses text templates and generates Starlark template - `InstructionSet` provides generic template instruction set for building Starlark templates `CompiledTemplate` uses to evaluate Starlark code is bundled `@ytt` library you can also make your own libraries as exemplified by `./hack/test-unit.sh` executes various basic validation tests Notable test locations: `pkg/cmd/template/*_test.go`: functional testing of `ytt` command (as a combination of various high level features e.g. data values, overlays, templating) `pkg/template/*_test.go`: mostly generic templating functionality `pkg/yamlmeta/*_test.go`: mostly YAML parsing tests `pkg/texttemplate/filetests/*`: functional testing of text templating (e.g. function definition, control flow) `pkg/yamltemplate/filetests/*`: functional testing of YAML templating (e.g. function definition, control flow) `pkg/yamltemplate/filetests/ytt-library/*`: functional testing of ytt provided modules (e.g. `base64`, `regexp`) `./hack/test-e2e.sh` executes various `examples/` directory content as end-to-end tests `pkg/website` contains HTML/JS/CSS source for ytt playground. `./hack/build.sh` combines those assets into a single file `pkg/website/generated.go` (using ytt itself ;) ) before building final binary. `ytt website` command can serve website locally. `./hack/build.sh && ytt website` can be used for pretty quick local iteration. Ultimately `get-ytt.io` runs on AWS Lambda, hence is wrapped with Lambda specific library. See `cmd/ytt-lambda-website/main.go` for details. library path: string that describes location of a library under yttlib in format "@lib1@nested-lib2". used in: `library.get("@...")` `load("@...")` library alias: string that is used in place of a path when referencing an instances of a library. Assigned via the alias kwarg to library.get(...). For example, the instance returned from `library.get("/github.com/folder/my-lib", alias=my-lib)` will be addressable in the `@library/ref` annotations using just

library ref: string that describes reference to a library under yttlib. The ref can be either the library path or library alias. For example, "@lib1@~foo". used in: `library/ref` annotation, e.g. `#@library/ref "@lib1@~foo"` data value flag, e.g. `-v @~foo:key=value` `ytt` prepares each template evaluation with a set of Starlark modules (e.g. `@ytt:data`, `@ytt:json`, `@ytt:template`). The source for this library is at `pkg/yttlibrary`. When contributing to this library note: Begin with the API before delving too deep into implementation, solidify the Starlark API (usually a conversation with a maintainer). this is codified in a couple of acceptance tests (`pkg/yamltemplate/filetests/ytt-library/...`) the goal is to provide a consistent, goal-aligned feature set. Design near Python and Go Starlark is a dialect of Python: to maintain the value of that heritage, be inspired by Python much of the functionality exposed can come from the Go ecosystem: to keep solutions simple, be inspired by Go. that said, this library is typically operating in a specific context: a hermetic and deterministic calculation of (YAML-formatted) configuration. Bend to adapt to that context. Offer string() rather than assume string encoding concrete types whose instances template authors will handle should implement `UnconvertableStarlarkValue` rather than assume to convert to a string. in the conversion hint, suggest they use `string()`. this preserves the ability to choose other encoding strategies, later, if desired. Names overall: look for conventions present in existing modules (e.g. `is_..()` for predicates, `string()` to encode to string, ...) module consider in combination with function names: be as concrete as possible, reveal intention, and avoid redundancy (e.g. `ip.parseaddr()` > `ip.parseip_addr()`) functions typically verb and verb phrases work best. built-in use the format "${module}.[${typename}.]${functionname}" (e.g. IPAddrValue.IsIPv4 => "ip.addr.is_ipv4") (this value is not yet used) Go definition of the Starlark function should almost always be the snakeCase format of the same name. Type() use the format "@ytt:${module}.${type}" (e.g. IPAddrValue => "@ytt:ip.addr" ) Fail fast users are usually better served by an error than an attempt to "guess" or "fix"; as soon as something seems ary, error out. Make Objects Immutable return modified copies rather than mutating the receiver: this tends to make template code that much easier to reason. built-in functions must return a valid `starlark.Value` Note: `nil` is not a valid `starlark.Value`; use `starlark.None` instead. Include Automated Tests include the ability to verify that your contribution (still) works, now and in the future at least demonstrate that the intended functionality works (i.e. cover the happy path case) should catch when a bump to underlying dependencies (if any) would cause a breaking change to your module such tests typically live in `pkg/yamltemplate/filetests/ytt-library` For your convenience, here's a list of PRs of prior contributions to the standard library: